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

Tool	Description
get_current_user	Identity of the authenticated account
list_groups	All groups with member balances
get_group	Full detail + simplified debts for one group
list_friends	All friends with balances owed/owing
list_expenses	Filterable expense list (group, friend, date range)
get_expense	Full detail for one expense
create_expense	Create an expense, split equally or with explicit shares
create_expenses_bulk	Create up to 50 expenses in one call; each succeeds/fails independently
update_expense	Update an existing expense
delete_expense	Delete an expense (destructive — clients should confirm first)
delete_expenses_bulk	Delete up to 100 expenses by id in one call (destructive — confirm first)
get_balances	Derived summary of who owes whom, across friends and groups

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, 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