Skip to main content
Glama
Splitwise MCP Server

Splitwise MCP Server

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

Related MCP server: Splitwise MCP Server

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

Available Tools

5 tools
create_expenseA

Create a new expense.

cost is a decimal string, e.g. "25.00". description is required.

Splitting:

  • Equal split (default): leave users empty; the cost is split evenly among everyone in the resolved group (group_id or SPLITWISE_GROUP_ID).

  • Custom split: pass users, a list of dicts each like {"user_id": 123, "paid_share": "25.00", "owed_share": "12.50"}. Identify a user by user_id, or by email/first_name/last_name. The paid_share values must sum to cost, and so must the owed_share values.

date accepts ISO 8601 (e.g. "2026-06-15T00:00:00Z"). currency_code is a 3-letter code (e.g. "USD"). category_id and details are optional.

Inputs: cost (required), description (required), date, users, +5 more. Returns: object

delete_expenseA

Delete an expense by id. Returns {"success": true} on success.

Inputs: expense_id (required). Returns: object

get_expenseA

Get the full details of a single expense by its id.

Inputs: expense_id (required). Returns: object

list_expensesA

List expenses, most recent first.

When group_id is omitted, the SPLITWISE_GROUP_ID default is used. Pass group_id=0 to list expenses across all groups and non-group expenses. Date filters (dated_after/before, updated_after/before) accept ISO 8601 strings, e.g. "2026-01-31T00:00:00Z".

Inputs: limit, offset, group_id, friend_id, +4 more. Returns: object

update_expenseA

Update an existing expense. Only provided fields are changed.

Note: if you pass users (custom shares), it overwrites ALL existing shares on the expense — include every participant. See create_expense for the users format and split rules.

Inputs: expense_id (required), cost, date, users, +5 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: create, delete, get, list, update. No overlap or ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., create_expense, list_expenses), making them predictable.

    Tool Count5/5

    5 tools is appropriate for the domain of expense management, covering core CRUD operations without unnecessary bloat.

    Completeness5/5

    The toolset covers all basic expense lifecycle operations (create, read, update, delete, list) with detailed split support, leaving no obvious gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      A standalone MCP server that provides complete access to the Splitwise API, enabling natural language management of expenses, groups, friends, and notifications in MCP-compatible clients like Claude Desktop and VS Code Copilot.
      9
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that enables AI clients like Codex, Claude Code, and Claude Desktop to manage Splitwise expenses, friends, groups, and more through natural language.
      2
      -