Which integrations are available for this server?

Enables management of Splitwise expenses with atomic duplicate prevention, including creating and deleting expenses, tracking split ratios between users, syncing expense caches, and querying expenses by date range or order ID.

How do I use Splitwise MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Splitwise MCP Server add a $49.99 Amazon electronics purchase from yesterday split 50/50" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Splitwise MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to manage Splitwise expenses with atomic duplicate prevention.

Features

Atomic Duplicate Prevention: Reserve-then-create pattern prevents accidental duplicate expenses from race conditions
Smart Duplicate Detection: Fuzzy matching on description, amount, and date within configurable windows
Local SQLite Cache: Fast duplicate checks without excessive API calls
Flexible Split Ratios: Support for any split percentage (50/50, 75/25, 100/0, etc.)
Order ID Tracking: Link expenses back to source orders (Amazon, Instacart, etc.) for traceability

Requirements

Python 3.10+
Splitwise API key
MCP-compatible client (Claude Code, etc.)

Installation

# Clone the repository git clone https://github.com/vishnujayvel/splitwise-mcp.git cd splitwise-mcp # Install in development mode pip install -e . # Or install with dev dependencies for testing pip install -e .[dev]

Configuration

The server supports multiple configuration methods, checked in this order:

Option 1: Environment Variables (Recommended for production)

export SPLITWISE_API_KEY="your_api_key" export SPLITWISE_GROUP_ID="your_group_id" export SPLITWISE_PAYER_ID="your_user_id" export SPLITWISE_PARTNER_ID="partner_user_id" # Optional: custom config file path export SPLITWISE_CONFIG_PATH="/path/to/config.json" # Optional: logging level (DEBUG, INFO, WARNING, ERROR) export LOG_LEVEL="INFO" # Optional: custom cache database path export SPLITWISE_CACHE_PATH="./splitwise_cache.db"

Option 2: Configuration File

Create a config.json file (see config.example.json):

{ "splitwise": { "api_key": "YOUR_SPLITWISE_API_KEY", "group_id": "YOUR_GROUP_ID", "payer_id": "YOUR_USER_ID", "partner_id": "PARTNER_USER_ID" } }

Getting Your Splitwise Credentials

API Key:
- Go to https://secure.splitwise.com/apps
- Click "Register your application"
- Fill in the application details
- Copy the API key
User IDs and Group ID:
- Go to https://secure.splitwise.com/api/v3.0/get_current_user (with authentication)
- Or use the Splitwise API to query your groups and members
- Your user ID and your partner's user ID are in the group members list

Usage with Claude Code

Add to your .mcp.json file:

{ "mcpServers": { "splitwise": { "command": "python", "args": ["-m", "splitwise_mcp.server"], "cwd": "/path/to/splitwise-mcp/src", "env": { "SPLITWISE_API_KEY": "your_api_key", "SPLITWISE_GROUP_ID": "your_group_id", "SPLITWISE_PAYER_ID": "your_user_id", "SPLITWISE_PARTNER_ID": "partner_user_id" } } } }

MCP Tools

splitwise_check_duplicate

Check if an expense would be a duplicate based on description, amount, and date similarity.

Input:

{ "description": "Amazon - Electronics", "amount": 49.99, "date": "2024-12-30", "group_id": "YOUR_GROUP_ID" }

Output:

{ "is_duplicate": false, "reason": "No duplicate found", "existing_expense_id": null, "similarity_score": 0.0 }

splitwise_reserve_expense

Atomically reserve an expense slot to prevent race conditions. Must be called before creating an expense.

Input:

{ "description": "Amazon - Electronics", "amount": 49.99, "date": "2024-12-30", "group_id": "YOUR_GROUP_ID", "order_id": "123-4567890-1234567" }

Output:

{ "reservation_id": "temp_abc123def456", "expires_at": "2024-12-30T12:05:00", "is_duplicate": false, "reason": "Reservation created successfully", "existing_expense_id": null }

splitwise_create_expense

Create an expense in Splitwise and confirm the reservation.

Input:

{ "reservation_id": "temp_abc123def456", "description": "Amazon - Electronics", "amount": 49.99, "date": "2024-12-30", "group_id": "YOUR_GROUP_ID", "payer_id": "YOUR_USER_ID", "partner_id": "PARTNER_USER_ID", "order_id": "123-4567890-1234567", "split_ratio": "50/50" }

Output:

{ "status": "created", "expense_id": "987654321", "payer_owes": 24.99, "partner_owes": 25.00, "total": 49.99, "url": "https://secure.splitwise.com/#/expenses/987654321" }

splitwise_sync_cache

Sync the local cache with Splitwise API. Fetches recent expenses and updates the cache.

Input:

{ "group_id": "YOUR_GROUP_ID", "since_date": "2024-12-01", "limit": 100 }

Output:

{ "synced_count": 15, "last_sync_at": "2024-12-30T12:00:00", "cache_size": 42 }

splitwise_get_expenses

Query expenses from the local cache (fast, no API call).

Input:

{ "group_id": "YOUR_GROUP_ID", "start_date": "2024-12-01", "end_date": "2024-12-31" }

Output:

{ "expenses": [ { "id": "987654321", "description": "Amazon - Electronics", "amount": 49.99, "date": "2024-12-30", "payer_owes": 24.99, "partner_owes": 25.00 } ], "total_count": 1 }

splitwise_delete_expense

Delete an expense from Splitwise and remove it from the cache.

Input:

{ "expense_id": "987654321", "group_id": "YOUR_GROUP_ID" }

Output:

{ "status": "deleted", "expense_id": "987654321" }

splitwise_find_by_order_id

Find an expense by order ID (most reliable duplicate detection method).

Input:

{ "order_id": "123-4567890-1234567" }

Output:

{ "found": true, "expense": { "expense_id": "987654321", "description": "Amazon - Electronics", "cost": 49.99, "date": "2024-12-30", "order_id": "123-4567890-1234567", "group_id": "YOUR_GROUP_ID" } }

Known Limitations

This is an early release optimized for two-person expense splitting (couples, roommates). The following features are not yet supported:

Feature	Status	Notes
Groups with 3+ members	Not supported	Hardcoded to payer + partner
Multiple groups	Not supported	Single group_id in config
Variable payer	Not supported	Payer always pays upfront
Expense categories	Not supported	-
Balance queries	Not supported	Use Splitwise app
Payment/settle-up	Not supported	Use Splitwise app
Expense editing	Not supported	Delete and recreate
Receipt images	Not supported	-

Contributions welcome for any of these features!

Troubleshooting

"Missing required configuration fields"

Ensure all required environment variables or config file fields are set:

SPLITWISE_API_KEY / api_key
SPLITWISE_GROUP_ID / group_id
SPLITWISE_PAYER_ID / payer_id
SPLITWISE_PARTNER_ID / partner_id

"Splitwise API error 401"

Your API key is invalid or expired. Generate a new one at https://secure.splitwise.com/apps

"Reservation expired"

Reservations expire after 5 minutes. Create the expense immediately after reserving, or reserve again.

Duplicate not detected

Run splitwise_sync_cache to update the local cache
Check that the expense date is within the duplicate detection window (default: 7 days)

Development

# Install dev dependencies pip install -e .[dev] # Run tests PYTHONPATH=src pytest tests/ -v # Run the server for testing python -m splitwise_mcp.server

License

MIT License - see LICENSE file for details.

Splitwise MCP Server

Splitwise MCP Server

Features

Requirements

Installation

Configuration

Option 1: Environment Variables (Recommended for production)

Option 2: Configuration File

Getting Your Splitwise Credentials

Usage with Claude Code

MCP Tools

splitwise_check_duplicate

splitwise_reserve_expense

splitwise_create_expense

splitwise_sync_cache

splitwise_get_expenses

splitwise_delete_expense

splitwise_find_by_order_id

Known Limitations

Troubleshooting

"Missing required configuration fields"

"Splitwise API error 401"

"Reservation expired"

Duplicate not detected

Development

License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API