open-splitwise
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@open-splitwise what's my total balance across all groups?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
Problem for agents | What open-splitwise does |
"Split dinner with Alice" requires 3–4 API calls + arithmetic |
|
Two Alices in your friends list |
|
"What do I owe?" needs multi-endpoint aggregation |
|
Splitwise returns | Server checks it; failures surface as tool errors with actionable text — never false success |
HTTP 429 rate limits | Retried invisibly ( |
Key revoked / logged out mid-session | Errors tell the agent the cause and to run |
33 tool schemas burn ~4k tokens in every prompt | Lazy tool discovery: only 7 essential tools are exposed by default; |
Related MCP server: Splitwise MCP Server
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_authvalidates a key live against Splitwise before storing it (wrong keys are never persisted),get_auth_statusexplains what's configured,logoutclears 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 carrydestructiveHint, 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, mode0600, atomic writes, never echoed back (masked previews only).
Quick start
git clone https://github.com/<you>/open-splitwise.git
cd open-splitwise
uv syncRun it standalone (stdio):
uv run open-splitwise # starts with no key configured — see auth belowGet 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: falseThen /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:
Situation | Agent-visible behavior |
No key anywhere | Every tool fails with: "No Splitwise API key is configured. Ask the user to generate one at secure.splitwise.com/apps, then call setup_auth." |
User provides a key |
|
Key revoked / account logged out (HTTP 401/403) | Tools fail with "key may have been revoked, expired, or the account was logged out… ask the user for a fresh key and call setup_auth" |
Diagnosis |
|
Switching accounts |
|
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; customowed_sharesvalidated to sum exactly; payer included by default (include_payer_in_split=falsewhen 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-currencyowed_to_you/you_owe/net, friend-level balances, and group simplified debts involving you.
Tool reference (33)
Group | Tools |
Workflows |
|
Users |
|
Groups |
|
Friends |
|
Expenses |
|
Comments |
|
Notifications |
|
Other |
|
Auth |
|
* 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
Env var | Default | Purpose |
| – | Bootstrap key (stored credentials take precedence) |
|
| Where |
|
| 429 retry attempts before surfacing |
|
|
|
Splitwise quirks handled for you
Array params flattened to Splitwise's odd
users__{index}__{property}encoding200 OK ≠ success:errors{}/success:falsechecked on every mutationMoney as decimal strings with 2 dp; remainder cents distributed, sums always exact
category_idmust be a subcategory — enforced via fuzzy name resolutionBalances/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.0Development
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 pathsBuilt 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.pyTerms 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.
Available Tools
7 toolsget_auth_statusARead-only
Report whether a Splitwise API key is configured, where it came from (stored credential vs environment), and a masked preview. Use this to diagnose auth failures.
Inputs: no named parameters.
logoutADestructive
Remove the stored Splitwise API key (log out). Environment-provided keys cannot be removed here and remain active as fallback.
Inputs: no named parameters.
money_summaryARead-only
One-call financial overview: per-currency totals of what you are owed vs what you owe across all friends, plus each friend's balance and simplified group debts. Replaces manual aggregation over get_friends/get_groups.
Inputs: no named parameters.
quick_add_expenseA
Agent-friendly expense creation from messy input. Participants can be names, partial names ('alice'), emails or user IDs; they are resolved automatically. Splits equally among participants plus the payer by default (set include_payer_in_split=false when the payer did not consume); pass owed_shares like {"Alice": "100.00"} for custom amounts that must sum to cost. category_name is fuzzy-matched against Splitwise categories; currency defaults to your default currency. Returns who owes what.
Inputs: cost (required), description (required), participants (required), date, +7 more.
resolve_usersARead-only
Resolve human-friendly identifiers (names, partial names, emails, user IDs, 'me') into Splitwise user IDs. Ambiguous names return candidate lists so you can ask the user which one they meant.
Inputs: queries (required).
search_toolsA
Discover the hidden raw Splitwise tools on demand (lazy loading keeps this server's default token footprint tiny).
With no query: returns a compact group index. With a query (e.g. 'expenses', 'groups', 'notifications' or a tool name): returns matching tools WITH their full input schemas and registers them into this session so they can be called directly. enable=false only reports. After enabling, clients that support tools/list_changed refresh automatically.
Inputs: query, enable.
setup_authA
Configure or replace the Splitwise API key. Validates the key against Splitwise before saving, so a wrong key is never stored. Ask the user to generate a personal API key at https://secure.splitwise.com/apps and pass it here.
Inputs: api_key (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each visible tool has a clearly distinct role: auth setup/status/logout form a lifecycle, resolve_users handles identifier mapping, quick_add_expense creates expenses, and money_summary provides balances. search_tools is explicitly a discovery/meta tool, so there is no meaningful overlap between tools.
Most tools follow a clear verb_noun snake_case pattern such as setup_auth, get_auth_status, resolve_users, quick_add_expense, and search_tools. logout and money_summary deviate slightly as a bare verb and a noun-noun phrase, but the naming remains easily predictable.
Seven tools is a well-scoped count for this server. It covers authentication, user lookup, expense creation, financial summary, and dynamic tool discovery without unnecessary bloat, and the lazy-loading design keeps the default surface compact.
The visible high-level tools cover auth, user resolution, expense creation, and summary, which handles common Splitwise workflows. search_tools explicitly exposes hidden raw tools for expenses, groups, and notifications, mitigating most gaps, though direct visible listing/update/delete expense helpers would make common management tasks more straightforward.
Maintenance
Related MCP Connectors
Manage Splitwise balances, expenses, and groups from your workspace. Fetch friends and recent acti…
Split bills from your AI: read bills & balances, create equal splits, request settlements.
Track shared expenses, balances, reminders and records. OAuth required; no money transfers.
Split group expenses, settle debts and track budgets in 107 currencies. Needs Spliteo Premium.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Splitwise expenses with atomic duplicate prevention, smart fuzzy matching, and support for flexible split ratios between two people.MIT
- AlicenseNot gradedqualityDmaintenanceEnables conversational control of Splitwise accounts through Claude AI, allowing users to add expenses, check group balances, record settlements, and manage payment splits using natural language commands. Supports multiple currencies and flexible splitting methods including equal, exact, and percentage-based divisions.1MIT
- AlicenseAqualityCmaintenanceEnables managing Splitwise expenses and generating premium spending analytics with category breakdowns, trends, and settlement optimization through natural language.42MIT
- AlicenseAqualityAmaintenanceConnects Claude to Splitwise for natural-language access to expenses, groups, friends, and balances.31399 npm1MIT