# 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).

## How it works

The server runs on your machine and talks to your MCP client over stdio. Each tool validates its input, calls Splitwise with your API key, and trims the response down to what a model needs.

```mermaid
flowchart LR
  Client["MCP client<br/>Claude Desktop, Claude Code, ..."]
  subgraph Local["splitwise-mcp, on your machine"]
    Tools["12 tools<br/>users, groups, friends,<br/>expenses, balances"]
    Schemas["Input schemas<br/>zod"]
    Bulk["Bulk create and delete<br/>up to 5 requests at once,<br/>a result per item"]
    API["Splitwise client<br/>API key from SPLITWISE_API_KEY"]
    Format["Response shaping<br/>compact JSON for the model"]
  end
  Splitwise["Splitwise API v3.0<br/>secure.splitwise.com"]

  Client -- "stdio, JSON-RPC" --> Tools
  Tools --> Schemas
  Tools --> Bulk
  Tools --> API
  Bulk --> API
  API -- "HTTPS, Bearer key" --> Splitwise
  API --> Format
  Format -- "tool result" --> Client

  classDef std fill:#56B4E9,stroke:#0072B2,color:#1a1a1a
  classDef ext fill:#E69F00,stroke:#a37100,color:#1a1a1a
  classDef hi fill:#009E73,stroke:#006B4E,color:#1a1a1a
  class Tools,Schemas,API,Format std
  class Bulk hi
  class Client,Splitwise ext
```

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