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.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Splitwise MCP Serveradd 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:
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_keySPLITWISE_GROUP_ID/group_idSPLITWISE_PAYER_ID/payer_idSPLITWISE_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_cacheto update the local cacheCheck 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.serverLicense
MIT License - see LICENSE file for details.
This server cannot be installed
Resources
Looking for Admin?
Admins can modify the Dockerfile, update the server description, and track usage metrics. If you are the server author, to access the admin panel.