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

Related MCP server: splitwise-mcp

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).