open-splitwise

Turn Splitwise into an agent-native expense tracker.

An open Model Context Protocol (MCP) server that lets any AI agent — Hermes, Claude Desktop, Claude Code, Cursor, or anything that speaks MCP — read balances, split expenses from messy natural language, diagnose its own auth problems, and never think about rate limits.

Python 3.11+ · MCP spec 2026-07-28 · stdio transport · 33 tools · lazy-loaded

Why

Existing Splitwise integrations hand the model a raw API mirror and hope for the best. That fails in predictable ways: the model invents category IDs, mis-splits ₹300 three ways, believes Splitwise's 200 OK when the request actually failed, or treats a rate-limit response as a bug to retry aggressively.

open-splitwise fixes this at the server layer:

Features

• Complete API coverage — all 27 endpoints of the official Splitwise OpenAPI 3.0 spec, one tool each, faithful names.
• Workflow layer — high-level tools so a single utterance maps to a single call.
• Self-service auth lifecycle — setup_auth validates a key live against Splitwise before storing it (wrong keys are never persisted), get_auth_status explains what's configured, logout clears credentials. Re-auth works mid-session.
• Honest errors — every failure mode (unresolved person, share-sum mismatch, unknown category, revoked key, exhausted retries) returns text telling the agent exactly what happened and what to do next.
• Safe-by-default annotations — reads carry readOnlyHint, destructive deletes carry destructiveHint, per MCP 2026-07-28 semantics. Tools register in deterministic order for cache-friendly discovery.
• Local-first secrets — API key stored at ~/.config/splitwise-mcp/credentials.json, mode 0600, atomic writes, never echoed back (masked previews only).

Quick start

git clone https://github.com/<you>/open-splitwise.git
cd open-splitwise
uv sync

Run it standalone (stdio):

uv run open-splitwise          # starts with no key configured — see auth below

Get an API key at https://secure.splitwise.com/apps (Account Settings → API keys).

Connect any MCP client

Generic stdio block (Claude Desktop claude_desktop_config.json, Claude Code .mcp.json, Cursor, …):

{
  "mcpServers": {
    "splitwise": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/open-splitwise", "run", "open-splitwise"],
      "env": { "SPLITWISE_API_KEY": "<optional: preconfigure>" }
    }
  }
}

Connect Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  splitwise:
    command: "uv"
    args: ["--directory", "/absolute/path/to/open-splitwise", "run", "open-splitwise"]
    env:
      SPLITWISE_API_KEY: "<optional>"
    tools:
      include: [quick_add_expense, resolve_users, money_summary, get_auth_status]
    prompts: false
    resources: false

Then /reload-mcp. Start with the four workflow/auth tools above; add raw API tools only when needed — Hermes' per-server filtering keeps the tool surface small.

Authentication lifecycle

The server is designed so agents diagnose and fix auth themselves, asking you only for the secret:

Key resolution happens per request: stored credential → SPLITWISE_API_KEY env var → none. A freshly saved key takes effect immediately in the running process — zero restarts.

Credentials live at ~/.config/splitwise-mcp/credentials.json (mode 0600). Override the directory with SPLITWISE_MCP_CONFIG_DIR (handy for tests or multi-profile setups).

Agent ergonomics

You:      "add dinner 900 split with alice and bob@x.com, groceries"
Agent:    quick_add_expense(description="Dinner", cost="900.00",
                            participants=["alice", "bob@x.com"],
                            category_name="groceries")
Server:   resolves alice→12? two matches! → error listing Alice A (id 10), Alice Wood (id 12)
Agent:    "Which Alice?"  → you answer → re-call succeeds
Server:   { status: created, expense_id: 99123,
            splits: [ "Nikhil paid 900.00 INR",
                      "Alice A owes 300.00 INR",
                      "Bob B owes 300.00 INR" ] }

• quick_add_expense — names/partial-names/emails/IDs accepted; equal shares computed with remainder cents distributed deterministically; custom owed_shares validated to sum exactly; payer included by default (include_payer_in_split=false when they didn't consume); currency defaults from your profile.
• resolve_users — email exact-match, full-name match, unique first-name, substring fallback; ambiguity returns candidates instead of guessing.
• money_summary — per-currency owed_to_you / you_owe / net, friend-level balances, and group simplified debts involving you.

Tool reference (33)

* annotated destructiveHint=true; all get_* tools annotated readOnlyHint=true. Prefer workflow tools over their raw counterparts whenever both exist.

Rate limiting

Splitwise answers HTTP 429 when throttled. open-splitwise retries automatically: Retry-After header honored verbatim; otherwise exponential backoff (0.5 s doubling, capped at 30 s), up to 3 attempts by default. Agents see an error only if every attempt is exhausted — and that error says to slow down, not retry blindly.

Configuration

Splitwise quirks handled for you

• Array params flattened to Splitwise's odd users__{index}__{property} encoding
• 200 OK ≠ success: errors{} / success:false checked on every mutation
• Money as decimal strings with 2 dp; remainder cents distributed, sums always exact
• category_id must be a subcategory — enforced via fuzzy name resolution
• Balances/debts read from pre-computed balance[] / simplified_debts (never recomputed)
• "Settle up" is just an expense with payment:true (no dedicated endpoint exists)
• OAuth2 exists but is deliberately out of scope: personal API keys fit the agent-asks-user flow; OAuth needs a redirect URI + browser (hosted deployments only)

Architecture

┌─────────────── any MCP client ───────────────┐
│  Hermes / Claude Desktop / Cursor / …        │
└──────────────────┬───────────────────────────┘
                   │ JSON-RPC over stdio
┌──────────────────▼───────────────────────────┐
│ server.py — FastMCP app, 33 tools            │
│   workflows · raw endpoints · auth lifecycle │
├──────────────────────────────────────────────┤
│ client.py — async REST client                │
│   bearer auth (per-request key resolution)   │
│   param flattening · success verification    │
│   transparent 429 retry/backoff              │
├──────────────────────────────────────────────┤
│ auth.py — credentials.json (0600, atomic)    │
└──────────────────┬───────────────────────────┘
                   │ HTTPS
          secure.splitwise.com/api/v3.0

Development

uv run pytest                        # 54 tests: client, rate limits, auth, workflows, lazy loading, MCP semantics
uv run python scripts/smoke_stdio.py # real subprocess: handshake, discovery, live auth-failure paths

Built test-first (strict TDD): every behavior above has a failing-test-first provenance. Layout:

src/open_splitwise/
  client.py    # REST client: auth provider, flattening, retry, error mapping
  auth.py      # credential storage
  server.py    # FastMCP definitions: workflows + raw + auth tools
tests/
scripts/smoke_stdio.py

Terms of use

Splitwise's self-serve API is non-commercial per their API terms. Your API key grants full access to your account — treat it like a password. This project is an independent integration and is not affiliated with or endorsed by Splitwise Inc.

Roadmap

• Receipt upload on expense creation
• Multi-currency expense helper with conversion awareness
• Recurring-expense summaries as an MCP prompt
• Optional Streamable HTTP transport for hosted/multi-user deployments (+OAuth2)
• Publish to PyPI (uvx open-splitwise)

Contributing

PRs welcome — please keep the TDD discipline (tests fail first, then pass), keep tool descriptions written for models, and never log secrets.

License

MIT — open for everyone: use it, modify it, ship it, sell with it. Just keep the copyright notice.