Splitwise MCP Server

A small MCP server (built with FastMCP) that wraps the Splitwise API so Claude can read and manage your expenses directly.

Tools

Tool	What it does
list_expenses	List expenses (filter by group, friend, date ranges; paginated)
get_expense	Get one expense's full details by id
create_expense	Add an expense — split equally or with custom per-user shares
update_expense	Edit an existing expense
delete_expense	Delete an expense

Credentials

Each user supplies their own Splitwise API key (and optional default group id). The server reads them per request, in this order:

1. HTTP request headers (multi-user / hosted) — preferred:

   Header	Required	Purpose
   X-Splitwise-Api-Key	yes	The caller's Splitwise API key (Bearer token)
   X-Splitwise-Group-Id	no	Default group id when a tool omits group_id

2. Environment variables (single-user / local fallback) — SPLITWISE_API_KEY, SPLITWISE_GROUP_ID.

This means one hosted deployment can serve many people: each person plugs in their own key via their client config — no shared key, no per-user redeploy.

Get an API key at dev.splitwise.com → Your apps → create an app → copy the API key. The group id is in the URL when you open a group on splitwise.com.

---

Deploy to FastMCP Cloud (hosted, multi-user)

FastMCP Cloud runs the server remotely and gives you one HTTPS URL that many people can use — each with their own key, passed as a header. You (the owner) don't need to put any Splitwise secret in the dashboard.

1. Push this folder to a GitHub repo (see "Git setup" below).

2. Go to fastmcp.cloud, sign in with GitHub, and create a project from your repo.

3. Set the entrypoint to:

   server.py:mcp
   

   (FastMCP Cloud installs dependencies from pyproject.toml automatically.)

4. Authentication: so other people can connect, set the project's access to public / unauthenticated. The real credential is each user's X-Splitwise-Api-Key header, so the server doesn't need its own login gate. (No SPLITWISE_* env vars needed in the dashboard for the multi-user case.)

5. Deploy. You'll get a URL like https://your-project.fastmcp.app/mcp. Share it.

How each user adds the server to Claude

Every user runs this with their own key and group id:

Claude Code (CLI):

claude mcp add --transport http splitwise https://your-project.fastmcp.app/mcp \
  --header "X-Splitwise-Api-Key: THEIR_API_KEY" \
  --header "X-Splitwise-Group-Id: THEIR_GROUP_ID"

Other clients (JSON form):

{
  "mcpServers": {
    "splitwise": {
      "url": "https://your-project.fastmcp.app/mcp",
      "headers": {
        "X-Splitwise-Api-Key": "THEIR_API_KEY",
        "X-Splitwise-Group-Id": "THEIR_GROUP_ID"
      }
    }
  }
}

Note: header-based config works in clients that support custom MCP headers (e.g. Claude Code). The Claude Desktop "Add custom connector" UI currently only takes a URL (no custom headers), so Desktop users would need a client that supports headers — or you'd move to OAuth. For most setups, Claude Code is the way each user plugs in their key.

---

Run locally (stdio, optional)

You can also run it on your own machine without the cloud. Here the secrets DO go in the Claude config (since the process runs locally):

uv sync   # install deps

Claude Code (CLI):

claude mcp add splitwise \
  -e SPLITWISE_API_KEY=your_api_key_here \
  -e SPLITWISE_GROUP_ID=your_default_group_id \
  -- uv run --directory /Users/azeemwaqar/Desktop/home/work/splitwise_mcp server.py

Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "splitwise": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/azeemwaqar/Desktop/home/work/splitwise_mcp", "server.py"],
      "env": {
        "SPLITWISE_API_KEY": "your_api_key_here",
        "SPLITWISE_GROUP_ID": "your_default_group_id"
      }
    }
  }
}

Inspect tools interactively:

uv run fastmcp dev server.py

---

Git setup (for FastMCP Cloud)

cd /Users/azeemwaqar/Desktop/home/work/splitwise_mcp
git init
git add .
git commit -m "Splitwise expense MCP server"
# create an empty repo on GitHub, then:
git remote add origin https://github.com/<you>/splitwise-mcp.git
git branch -M main
git push -u origin main

.env is git-ignored, so your key never gets committed.

Notes on splitting

• Equal split (default): omit users; the cost splits evenly across the group.
• Custom split: pass users, e.g. [{"user_id": 123, "paid_share": "25.00", "owed_share": "12.50"}, ...]. paid_share values must sum to cost, and so must owed_share. You can identify a user by user_id, or by email / first_name / last_name.

Scope is intentionally limited to expenses — no friends/groups/categories management tools (yet).