splitwise-mcp 2.0.1 → 2.0.2

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Splitwise — natural-language expense and group management via the Splitwise API",
-    "version": "1.3.0"
+    "version": "2.0.2"
   },
   "plugins": [
     {
@@ -15,14 +15,19 @@
       "displayName": "Splitwise",
       "source": "./",
       "description": "MCP server for Splitwise — manage expenses, groups, and friends via natural language",
-      "version": "1.3.0",
+      "version": "2.0.2",
       "author": {
         "name": "Chris Hall"
       },
       "homepage": "https://github.com/chrischall/splitwise-mcp",
       "repository": "https://github.com/chrischall/splitwise-mcp",
       "license": "MIT",
-      "keywords": ["splitwise", "expenses", "mcp", "finance"],
+      "keywords": [
+        "splitwise",
+        "expenses",
+        "mcp",
+        "finance"
+      ],
       "category": "finance"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "splitwise-mcp",
   "displayName": "Splitwise",
-  "version": "1.3.0",
+  "version": "2.0.2",
   "description": "MCP server for Splitwise — natural-language expense and group management via the Splitwise API",
   "author": {
     "name": "Chris Hall",
@@ -10,7 +10,12 @@
   "homepage": "https://github.com/chrischall/splitwise-mcp",
   "repository": "https://github.com/chrischall/splitwise-mcp",
   "license": "MIT",
-  "keywords": ["splitwise", "expenses", "mcp", "finance"],
+  "keywords": [
+    "splitwise",
+    "expenses",
+    "mcp",
+    "finance"
+  ],
   "skills": "./SKILL.md",
   "mcp": "./.mcp.json"
 }

package/README.md

@@ -0,0 +1,174 @@
+# Splitwise MCP
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that connects Claude to [Splitwise](https://www.splitwise.com), giving you natural-language access to your expenses, groups, friends, and balances.
+
+> [!WARNING]
+> **AI-developed project.** This codebase was entirely built and is actively maintained by [Claude Code](https://www.anthropic.com/claude). No human has audited the implementation. Review all code and tool permissions before use.
+
+## What you can do
+
+Ask Claude things like:
+
+- *"What do I owe?"*
+- *"Add a $50 dinner expense to the vacation group"*
+- *"Split this hotel bill 60/40 with Sarah"*
+- *"Who's in the trip group?"*
+- *"Add Meredith to the household group"*
+- *"Show me recent expenses"*
+- *"Delete that duplicate expense"*
+
+## Requirements
+
+- [Claude Desktop](https://claude.ai/download) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
+- [Node.js](https://nodejs.org) 20.6 or later
+- A [Splitwise](https://www.splitwise.com) account and API key
+
+## Installation
+
+### Option A -- npx (recommended)
+
+```bash
+npx -y splitwise-mcp
+```
+
+Add to your Claude config (`.mcp.json` or Claude Desktop config):
+
+```json
+{
+  "mcpServers": {
+    "splitwise": {
+      "command": "npx",
+      "args": ["-y", "splitwise-mcp"],
+      "env": {
+        "SPLITWISE_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Option B -- from source
+
+```bash
+git clone https://github.com/chrischall/splitwise-mcp.git
+cd splitwise-mcp
+npm install
+npm run build
+```
+
+Add to Claude Desktop config:
+
+- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "splitwise": {
+      "command": "node",
+      "args": ["/absolute/path/to/splitwise-mcp/dist/index.js"],
+      "env": {
+        "SPLITWISE_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Getting your API key
+
+1. Go to [secure.splitwise.com/apps/register](https://secure.splitwise.com/apps/register)
+2. Register an app (name and description can be anything)
+3. Copy the **API key** from the app detail page
+
+## Credentials
+
+| Env var | Required | Notes |
+|---------|----------|-------|
+| `SPLITWISE_API_KEY` | Yes | API key from [splitwise.com/apps/register](https://secure.splitwise.com/apps/register) |
+
+## Available tools
+
+20 tools across 5 domains. All tools are prefixed `sw_`.
+
+### User
+
+| Tool | What it does |
+|------|-------------|
+| `sw_get_current_user` | Get the authenticated user's profile |
+| `sw_get_user` | Get another user's profile by ID |
+
+### Groups
+
+| Tool | What it does |
+|------|-------------|
+| `sw_list_groups` | List all groups with members |
+| `sw_get_group` | Group details including members and balances |
+| `sw_create_group` | Create a new group |
+| `sw_delete_group` | Soft-delete a group |
+| `sw_undelete_group` | Restore a deleted group |
+| `sw_add_user_to_group` | Add a user to a group |
+| `sw_remove_user_from_group` | Remove a user from a group |
+
+### Friends
+
+| Tool | What it does |
+|------|-------------|
+| `sw_list_friends` | List all friends |
+| `sw_create_friend` | Add a friend by email |
+| `sw_delete_friend` | Remove a friendship |
+
+### Expenses
+
+| Tool | What it does |
+|------|-------------|
+| `sw_list_expenses` | List or search expenses with filters |
+| `sw_get_expense` | Full details of a single expense |
+| `sw_create_expense` | Create an expense (equal or custom split) |
+| `sw_update_expense` | Edit an existing expense |
+| `sw_delete_expense` | Soft-delete an expense |
+| `sw_undelete_expense` | Restore a deleted expense |
+| `sw_get_comments` | Get comments on an expense |
+| `sw_create_comment` | Add a comment to an expense |
+| `sw_delete_comment` | Delete a comment |
+
+### Utilities
+
+| Tool | What it does |
+|------|-------------|
+| `sw_get_notifications` | Recent activity feed |
+| `sw_get_categories` | Expense category list |
+| `sw_get_currencies` | Supported currency codes |
+
+## Troubleshooting
+
+**"SPLITWISE_API_KEY is required"** -- set the environment variable in your MCP config or a `.env` file.
+
+**429 rate limit** -- Splitwise has undocumented rate limits. Wait a moment and retry.
+
+**Tools not appearing in Claude** -- go to **Claude Desktop > Settings > Developer** to see connected servers. Make sure you fully quit and relaunched after editing the config.
+
+## Development
+
+```bash
+npm test        # run the test suite (vitest)
+npm run build   # compile TypeScript -> dist/
+```
+
+### Project structure
+
+```
+src/
+  client.ts         Splitwise API client (auth, request handling)
+  index.ts          MCP server entry point
+  tools/
+    user.ts         sw_get_current_user, sw_get_user
+    groups.ts       group CRUD and membership
+    friends.ts      friend list and management
+    expenses.ts     expense CRUD, comments
+    utilities.ts    notifications, categories, currencies
+```
+
+## License
+
+MIT

package/dist/bundle.js

@@ -30119,14 +30119,23 @@ import { fileURLToPath } from "url";
 try {
   const { config: config2 } = await import("dotenv");
   const __dirname = dirname(fileURLToPath(import.meta.url));
-  config2({ path: join(__dirname, "..", ".env"), override: false });
+  config2({ path: join(__dirname, "..", ".env"), override: false, quiet: true });
 } catch {
 }
+function readVar(key) {
+  const raw = process.env[key];
+  if (typeof raw !== "string") return void 0;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return void 0;
+  if (trimmed === "undefined" || trimmed === "null") return void 0;
+  if (/^\$\{[^}]*\}$/.test(trimmed)) return void 0;
+  return trimmed;
+}
 var BASE_URL = "https://secure.splitwise.com/api/v3.0";
 var SplitwiseClient = class {
   apiKey;
   constructor() {
-    const key = process.env.SPLITWISE_API_KEY;
+    const key = readVar("SPLITWISE_API_KEY");
     if (!key) throw new Error("SPLITWISE_API_KEY environment variable is required");
     this.apiKey = key;
   }

package/dist/client.js

@@ -4,16 +4,34 @@ import { fileURLToPath } from 'url';
 try {
     const { config } = await import('dotenv');
     const __dirname = dirname(fileURLToPath(import.meta.url));
-    config({ path: join(__dirname, '..', '.env'), override: false });
+    config({ path: join(__dirname, '..', '.env'), override: false, quiet: true });
 }
 catch {
     // not available — rely on process.env (mcpb sets credentials via mcp_config.env)
 }
+/**
+ * Read an env var, trim whitespace, and treat as unset if blank or if the value
+ * looks like an unsubstituted shell placeholder (e.g. `${FOO}`) — defends
+ * against MCP hosts that pass .mcp.json env blocks through unexpanded.
+ */
+function readVar(key) {
+    const raw = process.env[key];
+    if (typeof raw !== 'string')
+        return undefined;
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    if (trimmed === 'undefined' || trimmed === 'null')
+        return undefined;
+    if (/^\$\{[^}]*\}$/.test(trimmed))
+        return undefined;
+    return trimmed;
+}
 const BASE_URL = 'https://secure.splitwise.com/api/v3.0';
 export class SplitwiseClient {
     apiKey;
     constructor() {
-        const key = process.env.SPLITWISE_API_KEY;
+        const key = readVar('SPLITWISE_API_KEY');
         if (!key)
             throw new Error('SPLITWISE_API_KEY environment variable is required');
         this.apiKey = key;

package/package.json

@@ -1,12 +1,28 @@
 {
   "name": "splitwise-mcp",
-  "version": "2.0.1",
-  "description": "Splitwise MCP server for Claude — developed and maintained by AI (Claude Sonnet 4.6)",
-  "author": "Claude Sonnet 4.6 (AI) <https://www.anthropic.com/claude>",
+  "version": "2.0.2",
+  "mcpName": "io.github.chrischall/splitwise-mcp",
+  "description": "Splitwise MCP server for Claude — developed and maintained by AI (Claude Code)",
+  "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chrischall/splitwise-mcp.git"
   },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "ai",
+    "splitwise",
+    "expenses",
+    "expense-tracking",
+    "groups",
+    "friends",
+    "split-bills",
+    "finance",
+    "shared-expenses"
+  ],
   "type": "module",
   "bin": {
     "splitwise-mcp": "dist/index.js"
@@ -15,7 +31,8 @@
     "dist",
     ".claude-plugin",
     "SKILL.md",
-    ".mcp.json"
+    ".mcp.json",
+    "server.json"
   ],
   "scripts": {
     "build": "tsc && npm run bundle",

package/server.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.chrischall/splitwise-mcp",
+  "description": "Splitwise expense and group management for Claude — shared expenses, settle up, friends",
+  "repository": {
+    "url": "https://github.com/chrischall/splitwise-mcp",
+    "source": "github"
+  },
+  "version": "2.0.2",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "splitwise-mcp",
+      "version": "2.0.2",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "SPLITWISE_API_KEY",
+          "description": "Your Splitwise API key (splitwise.com/apps/api)",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true
+        }
+      ]
+    }
+  ]
+}