# splitwise-mcp

A local MCP (Model Context Protocol) server that exposes the [Splitwise API](https://dev.splitwise.com/) as tools, so MCP clients (Claude Desktop, Claude Code, etc.) can read and manage expenses, groups, and friends conversationally.

Runs entirely locally over stdio — no hosting, no public endpoint, no data leaves your machine except direct calls to `secure.splitwise.com`.

> This is an independent, unofficial project. It is not affiliated with, endorsed by, or supported by Splitwise, Inc.

**Requirements:** Node.js 18+ and a [Splitwise personal API key](https://secure.splitwise.com/apps).

## Tools

| Tool                   | Description                                                               |
| ---------------------- | ------------------------------------------------------------------------- |
| `get_current_user`     | Identity of the authenticated account                                     |
| `list_groups`          | All groups with member balances                                           |
| `get_group`            | Full detail + simplified debts for one group                              |
| `list_friends`         | All friends with balances owed/owing                                      |
| `list_expenses`        | Filterable expense list (group, friend, date range)                       |
| `get_expense`          | Full detail for one expense                                               |
| `create_expense`       | Create an expense, split equally or with explicit shares                  |
| `create_expenses_bulk` | Create up to 50 expenses in one call; each succeeds/fails independently   |
| `update_expense`       | Update an existing expense                                                |
| `delete_expense`       | Delete an expense (destructive — clients should confirm first)            |
| `delete_expenses_bulk` | Delete up to 100 expenses by id in one call (destructive — confirm first) |
| `get_balances`         | Derived summary of who owes whom, across friends and groups               |

Splitwise's API has no native bulk endpoint — the bulk tools fan out to the same per-expense calls as `create_expense`/`delete_expense`, with up to 5 requests in flight at once, and report a per-item `ok`/`error` result so a partial failure doesn't lose the rest of the batch.

## Setup

1. **Get a Splitwise API key**: go to [secure.splitwise.com/apps](https://secure.splitwise.com/apps), register an application, and copy the personal API key it gives you.
2. **Install dependencies and build**:
   ```sh
   npm install
   npm run build
   ```
3. **Run the tests** (optional, but recommended before wiring it into a client):
   ```sh
   npm test
   ```

## Client configuration

Add to your MCP client's config (e.g. Claude Desktop's `claude_desktop_config.json`, or Claude Code's `.mcp.json`):

```json
{
  "mcpServers": {
    "splitwise": {
      "command": "node",
      "args": ["/absolute/path/to/splitwise-mcp/build/index.js"],
      "env": {
        "SPLITWISE_API_KEY": "your-personal-api-key"
      }
    }
  }
}
```

Once published to npm (as `@tbmueller/splitwise-mcp` — the unscoped name belongs to an unrelated project), this can instead be:

```json
{
  "mcpServers": {
    "splitwise": {
      "command": "npx",
      "args": ["-y", "@tbmueller/splitwise-mcp"],
      "env": { "SPLITWISE_API_KEY": "your-personal-api-key" }
    }
  }
}
```

> **Never commit your API key.** Keep it only in your MCP client's config or a local, gitignored `.env` file — never in a tool input, a committed file, or a script argument that might end up in shell history.

## Development

```sh
npm run dev          # tsc --watch
npm test             # vitest run
npm run test:watch   # vitest
npm run format       # prettier --write .
npm run format:check # prettier --check . (used in CI)
npm run inspector    # build + launch MCP Inspector against the server
```

## Design notes

- Money amounts are handled as decimal strings end-to-end (never parsed to float) — share validation for `create_expense`/`update_expense` uses integer-cent arithmetic.
- Splitwise sometimes returns HTTP 200 with an `errors` object in the body instead of a non-2xx status; the client checks the body, not just the status code.
- Responses are trimmed of Splitwise's noisier fields (avatars, notification settings) before being returned to the model, to save context.
- See [PLAN.md](PLAN.md) for the original design plan and v2 candidates (group/friend management, comments, MCP resources).

## License

[MIT](LICENSE)