# splitwise-mcp

[![CI](https://github.com/harrydaihaolin/splitwise-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/harrydaihaolin/splitwise-mcp/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

An [MCP](https://modelcontextprotocol.io) server for [Splitwise](https://splitwise.com).
Manage expenses, balances, settlements, groups, and comments in natural
language from Claude Code, Claude Desktop, or any MCP client.

> "I paid $40 for dinner, split evenly with Alex and Sam."
> "What's my balance with the apartment group?"
> "Record that I paid Sam back $15."

## Tools

| Category    | Tools |
|-------------|-------|
| User        | `whoami` |
| Friends     | `list_friends` |
| Groups      | `list_groups`, `get_group` |
| Expenses    | `list_expenses`, `get_expense`, `create_expense`, `update_expense`, `delete_expense` |
| Two-party shortcuts | `split_with`, `lend_to`, `borrow_from` |
| Settlements | `record_payment` |
| Comments    | `list_comments`, `add_comment` |

### Two-party shortcuts

For the everyday actions between you and one friend, these wrap `create_expense`
and resolve "you" automatically (via `whoami`):

- **`split_with(friend_id, cost, description, i_paid=True)`** — 50/50 split,
  cent-accurate. Set `i_paid=False` if the friend paid.
- **`lend_to(friend_id, cost, description)`** — you paid; the friend owes you
  the full amount.
- **`borrow_from(friend_id, cost, description)`** — the friend paid; you owe
  them the full amount.

The fourth everyday action — **skip** — is just doing nothing, so there's no
tool for it.

The server is a thin wrapper over the Splitwise API: the agent resolves a
person's name to a user id with `list_friends`, then calls `create_expense` or
`record_payment`. Equal splits are computed cent-accurately server-side; uneven
splits are passed explicitly via `shares`.

## Setup

### 1. Get a Splitwise API key

Go to <https://secure.splitwise.com/apps>, register an app, and copy your
**API key** (a personal access token).

### 2. Install

Requires Python ≥ 3.10.

```bash
git clone https://github.com/harrydaihaolin/splitwise-mcp
cd splitwise-mcp
uv sync            # or: pip install -e .
```

### 3. Add to Claude Code

```bash
claude mcp add splitwise \
  --env SPLITWISE_API_KEY=your_key_here \
  -- uvx --from /absolute/path/to/splitwise-mcp splitwise-mcp
```

Or run the module directly:

```bash
SPLITWISE_API_KEY=your_key_here python -m splitwise_mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "splitwise": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/splitwise-mcp", "splitwise-mcp"],
      "env": { "SPLITWISE_API_KEY": "your_key_here" }
    }
  }
}
```

## Development

```bash
uv sync --extra dev
uv run pytest
```

Tests use `httpx.MockTransport` and a fake client — no live API calls.

## Design

See [`docs/specs/2026-06-03-splitwise-mcp-design.md`](docs/specs/2026-06-03-splitwise-mcp-design.md).

## Security

Your API key has full read/write access to your Splitwise account. It is read
only from the `SPLITWISE_API_KEY` environment variable and never logged. Treat
it like a password.

## License

MIT — see [LICENSE](LICENSE).