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.

How it works

The server runs on your machine and talks to your MCP client over stdio. Each tool validates its input, calls Splitwise with your API key, and trims the response down to what a model needs.

flowchart LR
  Client["MCP client<br/>Claude Desktop, Claude Code, ..."]
  subgraph Local["splitwise-mcp, on your machine"]
    Tools["12 tools<br/>users, groups, friends,<br/>expenses, balances"]
    Schemas["Input schemas<br/>zod"]
    Bulk["Bulk create and delete<br/>up to 5 requests at once,<br/>a result per item"]
    API["Splitwise client<br/>API key from SPLITWISE_API_KEY"]
    Format["Response shaping<br/>compact JSON for the model"]
  end
  Splitwise["Splitwise API v3.0<br/>secure.splitwise.com"]

  Client -- "stdio, JSON-RPC" --> Tools
  Tools --> Schemas
  Tools --> Bulk
  Tools --> API
  Bulk --> API
  API -- "HTTPS, Bearer key" --> Splitwise
  API --> Format
  Format -- "tool result" --> Client

  classDef std fill:#56B4E9,stroke:#0072B2,color:#1a1a1a
  classDef ext fill:#E69F00,stroke:#a37100,color:#1a1a1a
  classDef hi fill:#009E73,stroke:#006B4E,color:#1a1a1a
  class Tools,Schemas,API,Format std
  class Bulk hi
  class Client,Splitwise ext

Related MCP server: Splitwise MCP Server

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.

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 (as @tbmueller/splitwise-mcp — the unscoped name belongs to an unrelated project), this can instead be:

{
  "mcpServers": {
    "splitwise": {
      "command": "npx",
      "args": ["-y", "@tbmueller/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