splitwise-mcp: Instructions file for Claude Code

Splitwise MCP Server

Project Overview

This is a Model Context Protocol (MCP) server for managing Splitwise expenses with atomic duplicate prevention. It enables AI assistants like Claude to create, query, and manage shared expenses.

Architecture

src/splitwise_mcp/
├── server.py   - MCP server with tool definitions
├── client.py   - Splitwise API client wrapper
├── cache.py    - Local SQLite caching layer
├── tools.py    - Tool handler implementations
└── config.py   - Configuration loading utilities

Key Features

1. Atomic Reservation Pattern - Reserve-then-create prevents duplicate expenses
2. Duplicate Detection - Fuzzy matching on description, amount, and date
3. Local SQLite Cache - Fast lookups without API calls
4. Flexible Split Ratios - Support for any percentage (50/50, 75/25, etc.)
5. Order ID Tracking - Link expenses to source orders for traceability

Development Commands

# Install in development mode
pip install -e .[dev]

# Run tests
PYTHONPATH=src pytest tests/ -v

# Start MCP server
python -m splitwise_mcp.server

# Test with MCP Inspector
npx @modelcontextprotocol/inspector python -m splitwise_mcp.server

Configuration

The server loads configuration in this priority order:

1. Environment variables (SPLITWISE_API_KEY, SPLITWISE_GROUP_ID, etc.)
2. File specified by SPLITWISE_CONFIG_PATH environment variable
3. ./config.json in the current directory

Required configuration fields:

• api_key - Splitwise API key
• group_id - Target group ID
• payer_id - Primary payer's user ID
• partner_id - Partner's user ID

MCP Tools

Tool	Description
splitwise_check_duplicate	Check if expense would be a duplicate
splitwise_reserve_expense	Atomically reserve an expense slot
splitwise_create_expense	Create expense with reservation
splitwise_sync_cache	Sync local cache with Splitwise API
splitwise_get_expenses	Query cached expenses
splitwise_delete_expense	Delete an expense
splitwise_find_by_order_id	Find expense by order ID