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_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 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.