Splitwise MCP Server

A Model Context Protocol (MCP) server that integrates with Splitwise. Connect your AI assistant (Claude, Cursor, etc.) to manage Splitwise expenses using natural language — with voice support!

How It Works

flowchart LR
    Client[Claude / Cursor] -->|MCP| Server[splitwise-mcp]
    Server -->|audio| Deepgram[Deepgram STT]
    Deepgram -->|text| Gemini[Gemini 3 Flash]
    Gemini -->|action| Splitwise[Splitwise API]

Features

Tool	Description
voice_command	Send audio → Deepgram transcribes → Gemini processes → Splitwise executes
text_command	Send text → Gemini processes → Splitwise executes
add_expense	Add expenses with support for groups, percentages, exclusions, and specific payers
delete_expense	Delete an expense by ID
list_friends	List your Splitwise friends
configure_splitwise	Configure API credentials
login_with_token	Login with OAuth2 token

Smart Name Matching: If Deepgram transcribes "Humeet" but your friend is "Sumeet", Gemini will ask for clarification instead of guessing.

Advanced Splits

• Percentages: "Split 40% for me and 60% for Alice"
• Groups: "Add to Apartment group" (Auto-fetches members)
• Exclusions: "Add to Apartment but exclude Bob"
• Payer: "Alice paid $50"
• Deletion: "Delete expense 12345"

Installation

Option 1: Install from PyPI (Recommended)

pip install splitwise-mcp

Option 2: Install from Source

1. Clone the repository:

   git clone https://github.com/hubshashwat/the-splitwise-mcp.git
   cd the-splitwise-mcp
   

2. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install the package:

   pip install -e .
   

Configuration

You'll need API keys depending on which features you want:

Required (Core Splitwise Features)

1. Splitwise API Keys (https://secure.splitwise.com/apps/new)
   • Register a new application
   • Get: Consumer Key, Consumer Secret, and API Key
   • Required for: add_expense, list_friends, delete_expense

Optional (AI Features)

2. Gemini API Key (https://aistudio.google.com/) - Optional

   • Create API key (free tier available)
   • Model: Uses Gemini 3.0 Flash - ensure your API key has access to this model
   • Required for: text_command (natural language processing)

3. Deepgram API Key (https://console.deepgram.com/) - Optional

   • Sign up and get API key (free tier available)
   • Required for: voice_command (audio transcription)

Summary:

• Text-only users: Need Splitwise + Gemini keys (skip Deepgram)
• Voice users: Need all 5 keys
• Basic API users: Only need 3 Splitwise keys

Set environment variables in your shell or add to your Claude Desktop config (see below).

Usage

You can use this server in two ways:

Option A: Standalone Terminal Agent (No Claude Required!) 🖥️

Run the voice/text agent directly in your terminal:

# Install the package
pip install splitwise-mcp

# Download the agent script
curl -O https://raw.githubusercontent.com/hubshashwat/the-splitwise-mcp/main/run_agent.py

# Set environment variables
export SPLITWISE_CONSUMER_KEY="your_key"
export SPLITWISE_CONSUMER_SECRET="your_secret"  
export SPLITWISE_API_KEY="your_api_key"
export GEMINI_API_KEY="your_gemini_key"
export DEEPGRAM_API_KEY="your_deepgram_key"

# Run the agent
python run_agent.py

Commands:

• v or voice - Record 10 seconds of audio and process it
• t or text - Type your command
• q or quit - Exit

Example session:

🤖 Splitwise Voice Agent
Enter command (voice/text/quit): t
Enter request: Add expense of $50 with John for dinner

⚠️  Proposed Action:
   Function: add_expense
   Args: {
     "description": "dinner",
     "cost": 50.0,
     "split_with": ["John"]
   }

Proceed? (yes/edit/cancel): yes
✅ Expense added!

Option B: With MCP Clients 💬

This server uses stdio transport and works with all MCP-compatible clients:

Claude Desktop

Add to your config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "splitwise": {
      "command": "full path of python",
      "args": ["-m", "splitwise_mcp.server"],
      "env": {
        "SPLITWISE_CONSUMER_KEY": "your_consumer_key",
        "SPLITWISE_CONSUMER_SECRET": "your_consumer_secret",
        "SPLITWISE_API_KEY": "your_api_key",
        "GEMINI_API_KEY": "your_gemini_key",
        "DEEPGRAM_API_KEY": "your_deepgram_key"
      }
    }
  }
}

Note: If splitwise-mcp console command is available, you can use "command": "splitwise-mcp" without args instead.

Then in Claude: "Add an expense of $50 with John for dinner"

Claude CLI

Use the same config format with claude-cli --mcp-config.

Cursor / VS Code (Antigravity, Cline, Continue.dev)

Add to your MCP settings (.vscode/settings.json or Cursor settings):

{
  "mcp.servers": {
    "splitwise": {
      "command": "full path of python",
      "args": ["-m", "splitwise_mcp.server"],
      "env": {
        "SPLITWISE_CONSUMER_KEY": "your_consumer_key",
        "SPLITWISE_CONSUMER_SECRET": "your_consumer_secret",
        "SPLITWISE_API_KEY": "your_api_key",
        "GEMINI_API_KEY": "your_gemini_key",
        "DEEPGRAM_API_KEY": "your_deepgram_key"
      }
    }
  }
}

Then you can ask your AI assistant: "Use Splitwise to add an expense..."

Other MCP Clients

This server is compatible with any MCP client supporting stdio transport. Use the same configuration pattern.

---

Note: If you installed from source instead of pip, use the full path to the executable:

• macOS/Linux: "/path/to/the-splitwise-mcp/.venv/bin/splitwise-mcp"
• Windows: "C:\\path\\to\\the-splitwise-mcp\\.venv\\Scripts\\splitwise-mcp.exe"

Remote Access (SSE)

To run the MCP server over HTTP for remote clients:

.venv/bin/uvicorn splitwise_mcp.sse:app --host 0.0.0.0 --port 8000

Connect via: http://YOUR_IP:8000/sse

Development

Run tests:

.venv/bin/python tests/test_logic.py

Troubleshooting

Microphone Issues (macOS)

If the agent says "Recording finished" immediately but captures no audio (Volume: 0.0), your terminal likely lacks microphone permission.

1. Go to System Settings > Privacy & Security > Microphone.
2. Enable access for your terminal app (Terminal, iTerm, VS Code, etc.).
3. Restart your terminal for changes to take effect.

License

MIT