Splitwise MCP Server

Read-only MCP server for analyzing Splitwise data from MCP-compatible clients like Claude.

What It Exposes

The server is intentionally read-only. It validates API keys and only returns data from groups the authenticated user belongs to.

Tools:

• get_user_context - User info, groups, memberships
• list_expenses - Detailed expense rows with filters
• get_spending_report_data - Aggregated spending analysis
• get_group_balances - Settlement balances by group
• get_budget_data - Personal budget data by month

Use these tools to give an AI raw facts and structured report data. The AI client should do the actual analysis.

How It Works

This MCP server is a lightweight HTTP client that talks to your Splitwise backend API:

Claude Desktop
    ↓ (API Key)
MCP Server (npx @yourname/splitwise-mcp)
    ↓ (validates key + fetches data)
Your Splitwise Backend (/api/mcp/*)
    ↓
MongoDB

Security benefits:

• ✅ No database credentials needed
• ✅ API keys can be revoked anytime from the web UI
• ✅ Server-side auth validation
• ✅ Users only see their own data
• ✅ Easy to deploy, no path dependencies

Installation

npm install -g @yourname/splitwise-mcp
# or just use npx

Environment Variables

Required:

MCP_API_KEY="sk_splitwise_..."       # Generated from /profile/integrations
SPLITWISE_API_URL="http://localhost:3000"  # Your Splitwise app (optional, defaults to localhost)

Setup for Friends

1. Host goes to their app at /profile/integrations
2. Clicks "Create API Key" and names it (e.g., "Sarah's Laptop")
3. Copies the full JSON config block shown
4. Friend pastes into ~/Library/Application Support/Claude/claude_desktop_config.json
5. Friend restarts Claude Desktop → Done!

Example Claude Desktop Config

When you create an API key, the app shows the exact JSON to paste:

{
  "mcpServers": {
    "splitwise": {
      "command": "npx",
      "args": ["@yourname/splitwise-mcp"],
      "env": {
        "MCP_API_KEY": "sk_splitwise_93ea72ba88655ed7b8b0a417e9472b17db1024fb4907c88681f66b0ac3b9c093",
        "SPLITWISE_API_URL": "http://localhost:3000"
      }
    }
  }
}

Run Locally (Development)

MCP_API_KEY="your-api-key-here" npm run mcp:splitwise

The server uses stdio, so it is meant to be launched by an MCP client (Claude Desktop).

Example Analysis Prompts

Once connected, try:

• "Use my Splitwise MCP data. Why was this month expensive compared to last month?"
• "Which groups are creating the most cash-flow pressure for me?"
• "Find unusual expenses this quarter and ask follow-up questions if needed."
• "Compare my budget lines to actual spending this month."
• "Which category labels look messy or too broad?"

Security Notes

• No write tools — read-only access only
• API keys are revocable — generate new ones, revoke old ones anytime from the web UI
• Data scoped to user — each API key only returns data for that specific user
• Backend auth — API keys are validated server-side against the database
• No credentials in client — users only need an API key, not MongoDB/database credentials

Deployment

To publish as an npm package:

npm publish --access public
# or scoped:
npm publish --access public --scope=@yourname

Then users install with:

npm install -g @yourname/splitwise-mcp