# 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

```bash
# 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)

```bash
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`):

```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

1. **API Key**:
   - Go to https://secure.splitwise.com/apps
   - Click "Register your application"
   - Fill in the application details
   - Copy the API key

2. **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:

```json
{
  "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:**
```json
{
  "description": "Amazon - Electronics",
  "amount": 49.99,
  "date": "2024-12-30",
  "group_id": "YOUR_GROUP_ID"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "description": "Amazon - Electronics",
  "amount": 49.99,
  "date": "2024-12-30",
  "group_id": "YOUR_GROUP_ID",
  "order_id": "123-4567890-1234567"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "group_id": "YOUR_GROUP_ID",
  "since_date": "2024-12-01",
  "limit": 100
}
```

**Output:**
```json
{
  "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:**
```json
{
  "group_id": "YOUR_GROUP_ID",
  "start_date": "2024-12-01",
  "end_date": "2024-12-31"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "expense_id": "987654321",
  "group_id": "YOUR_GROUP_ID"
}
```

**Output:**
```json
{
  "status": "deleted",
  "expense_id": "987654321"
}
```

### splitwise_find_by_order_id

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

**Input:**
```json
{
  "order_id": "123-4567890-1234567"
}
```

**Output:**
```json
{
  "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

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

## Development

```bash
# 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](LICENSE) file for details.