splitwise-mcp

A local MCP (Model Context Protocol) server that exposes the Splitwise API as tools, so MCP clients (Claude Desktop, Claude Code, etc.) can read and manage expenses, groups, and friends conversationally.

Runs entirely locally over stdio — no hosting, no public endpoint, no data leaves your machine except direct calls to secure.splitwise.com.

This is an independent, unofficial project. It is not affiliated with, endorsed by, or supported by Splitwise, Inc.

Requirements: Node.js 18+ and a Splitwise personal API key.

Tools

Splitwise's API has no native bulk endpoint — the bulk tools fan out to the same per-expense calls as create_expense/delete_expense, with up to 5 requests in flight at once, and report a per-item ok/error result so a partial failure doesn't lose the rest of the batch.

Related MCP server: Splitwise MCP Server

Setup

1. Get a Splitwise API key: go to secure.splitwise.com/apps, register an application, and copy the personal API key it gives you.

2. Install dependencies and build:

   npm install
   npm run build

3. Run the tests (optional, but recommended before wiring it into a client):

   npm test

Client configuration

Add to your MCP client's config (e.g. Claude Desktop's claude_desktop_config.json, or Claude Code's .mcp.json):

{
  "mcpServers": {
    "splitwise": {
      "command": "node",
      "args": ["/absolute/path/to/splitwise-mcp/build/index.js"],
      "env": {
        "SPLITWISE_API_KEY": "your-personal-api-key"
      }
    }
  }
}

Once published to npm, this can instead be:

{
  "mcpServers": {
    "splitwise": {
      "command": "npx",
      "args": ["-y", "splitwise-mcp"],
      "env": { "SPLITWISE_API_KEY": "your-personal-api-key" }
    }
  }
}

Never commit your API key. Keep it only in your MCP client's config or a local, gitignored .env file — never in a tool input, a committed file, or a script argument that might end up in shell history.

Development

npm run dev          # tsc --watch
npm test             # vitest run
npm run test:watch   # vitest
npm run format       # prettier --write .
npm run format:check # prettier --check . (used in CI)
npm run inspector    # build + launch MCP Inspector against the server

Design notes

• Money amounts are handled as decimal strings end-to-end (never parsed to float) — share validation for create_expense/update_expense uses integer-cent arithmetic.

• Splitwise sometimes returns HTTP 200 with an errors object in the body instead of a non-2xx status; the client checks the body, not just the status code.

• Responses are trimmed of Splitwise's noisier fields (avatars, notification settings) before being returned to the model, to save context.

• See PLAN.md for the original design plan and v2 candidates (group/friend management, comments, MCP resources).

License

MIT