splitwise-mcp

An MCP server for Splitwise. Manage expenses, balances, settlements, groups, and comments in natural language from Claude Code, Claude Desktop, or any MCP client.

"I paid $40 for dinner, split evenly with Alex and Sam." "What's my balance with the apartment group?" "Record that I paid Sam back $15."

Tools

Category	Tools
User	whoami
Friends	list_friends
Groups	list_groups, get_group
Expenses	list_expenses, get_expense, create_expense, update_expense, delete_expense
Two-party shortcuts	split_with, lend_to, borrow_from
Settlements	record_payment
Comments	list_comments, add_comment

Two-party shortcuts

For the everyday actions between you and one friend, these wrap create_expense and resolve "you" automatically (via whoami):

• split_with(friend_id, cost, description, i_paid=True) — 50/50 split, cent-accurate. Set i_paid=False if the friend paid.
• lend_to(friend_id, cost, description) — you paid; the friend owes you the full amount.
• borrow_from(friend_id, cost, description) — the friend paid; you owe them the full amount.

The fourth everyday action — skip — is just doing nothing, so there's no tool for it.

The server is a thin wrapper over the Splitwise API: the agent resolves a person's name to a user id with list_friends, then calls create_expense or record_payment. Equal splits are computed cent-accurately server-side; uneven splits are passed explicitly via shares.

Setup

1. Get a Splitwise API key

Go to https://secure.splitwise.com/apps, register an app, and copy your API key (a personal access token).

2. Install

Requires Python ≥ 3.10.

git clone https://github.com/harrydaihaolin/splitwise-mcp
cd splitwise-mcp
uv sync            # or: pip install -e .

3. Add to Claude Code

claude mcp add splitwise \
  --env SPLITWISE_API_KEY=your_key_here \
  -- uvx --from /absolute/path/to/splitwise-mcp splitwise-mcp

Or run the module directly:

SPLITWISE_API_KEY=your_key_here python -m splitwise_mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "splitwise": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/splitwise-mcp", "splitwise-mcp"],
      "env": { "SPLITWISE_API_KEY": "your_key_here" }
    }
  }
}

Development

uv sync --extra dev
uv run pytest

Tests use httpx.MockTransport and a fake client — no live API calls.

Design

See docs/specs/2026-06-03-splitwise-mcp-design.md.

Security

Your API key has full read/write access to your Splitwise account. It is read only from the SPLITWISE_API_KEY environment variable and never logged. Treat it like a password.

License

MIT — see LICENSE.