SplitwiseMCP

Installation guide for the Splitwise MCP server. The MCP server implementation and app-specific documentation live in MCP_files/.

What This Installs

This repo provides a local Model Context Protocol server for Splitwise. After setup, MCP clients such as Codex, Claude Code, and Claude Desktop can use Splitwise tools for expenses, friends, groups, comments, currencies, categories, notifications, and raw documented API calls.

Fetch Splitwise Keys

You need three values before installation:

• SPLITWISE_CONSUMER_KEY
• SPLITWISE_CONSUMER_SECRET
• SPLITWISE_API_KEY

Get them from Splitwise:

1. Open https://secure.splitwise.com/apps
2. Sign in to Splitwise.
3. Create a new app, or open an existing app.
4. Copy the Consumer Key.
5. Copy the Consumer Secret.
6. Generate or copy the API key from the app details page.

Treat the API key like a password. The installer writes it to .env, and .env is ignored by git.

Install

From the repo root:

chmod +x install.sh
./install.sh

The installer prompts for the three Splitwise values one after another, writes them to .env, locks the file to mode 600, and can install dependencies into venv.

Manual dependency install:

python3 -m venv venv
venv/bin/python -m pip install --upgrade pip
venv/bin/python -m pip install -r requirements.txt

Codex CLI Setup

Copy and paste from the repo root:

codex mcp add splitwise -- "$(pwd)/venv/bin/python" "$(pwd)/MCP_files/server.py"

Restart Codex or start a new Codex session.

Claude Code CLI Setup

Copy and paste from the repo root:

claude mcp add splitwise -- "$(pwd)/venv/bin/python" "$(pwd)/MCP_files/server.py"

Restart Claude Code or start a new session.

Claude Desktop Setup

Open Claude Desktop's MCP/server configuration and add this server manually.

Use this JSON, replacing /absolute/path/to/SplitwiseMCP with your local repo path:

{
  "mcpServers": {
    "splitwise": {
      "type": "stdio",
      "command": "/absolute/path/to/SplitwiseMCP/venv/bin/python",
      "args": ["/absolute/path/to/SplitwiseMCP/MCP_files/server.py"],
      "env": {}
    }
  }
}

Restart Claude Desktop after updating the config.

Project Layout

.
├── README.md
├── install.sh
├── requirements.txt
├── .env.example
└── MCP_files/
    ├── README.md
    ├── server.py
    ├── interactive.py
    ├── openapi.json
    └── claude_desktop_config.example.json

Security

• Never commit .env.
• Rotate your Splitwise API key if it is exposed.
• Mutating tools can create, update, delete, and restore Splitwise records. Use read-only tools first if you are unsure.