# Splitwise MCP

[![CI](https://github.com/chrischall/splitwise-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/chrischall/splitwise-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/splitwise-mcp)](https://www.npmjs.com/package/splitwise-mcp)
[![license](https://img.shields.io/npm/l/splitwise-mcp)](LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) server that connects Claude to [Splitwise](https://www.splitwise.com), giving you natural-language access to your expenses, groups, friends, and balances.

> [!WARNING]
> **AI-developed project.** This codebase was entirely built and is actively maintained by [Claude Code](https://www.anthropic.com/claude). No human has audited the implementation. Review all code and tool permissions before use.

## What you can do

Ask Claude things like:

- *"What do I owe?"*
- *"Add a $50 dinner expense to the vacation group"*
- *"Split this hotel bill 60/40 with Sarah"*
- *"Who's in the trip group?"*
- *"Add Sam to the household group"*
- *"Show me recent expenses"*
- *"Delete that duplicate expense"*
- *"Download the receipt from that hotel expense"*
- *"Add that Amazon order screenshot as the receipt on the water-jug expense"*
- *"Log $250.01 camp, Sam paid, split 50/50"*
- *"Find every 'example' expense this year, including deleted ones, and why they were deleted"*

## Requirements

- [Claude Desktop](https://claude.ai/download) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
- [Node.js](https://nodejs.org) 22 or later
- A [Splitwise](https://www.splitwise.com) account and API key

## Acknowledgement of Terms

By using this MCP server, you acknowledge and agree to the following:

**1. This server accesses your own Splitwise account via Splitwise's official Developer API.** Auth happens via your own API consumer key + secret, which Splitwise issues to you when you register an app. It does not — and cannot — access anyone else's expenses or groups.

**2. [Splitwise's Developer Terms](https://dev.splitwise.com/) govern your use of this server**. The clauses most relevant here:

> You will use Splitwise Materials solely as necessary to develop, test and support a Self-Service integration of your software application… with Splitwise.

And on rate limits: *"You will not use the API in a manner that exceeds rate limits, or constitutes excessive or abusive usage."* And on competitive use: *"You may not [use] Splitwise Materials to create an application that replicates existing Splitwise functionality or competes with Splitwise."*

You are agreeing to those terms — read by the maintainer 2026-05-23 — every time you invoke a tool in this server.

**3. Personal, non-commercial use only.** This project is not affiliated with, endorsed by, sponsored by, or in partnership with Splitwise, Inc. It is a personal automation tool that calls the documented public Splitwise REST API on your own account. Do not use it to commercialize Splitwise data, compete with Splitwise's product, or share API credentials with third parties.

**4. Your API key is yours alone.** Splitwise issues credentials per-app, per-developer. **Do not commit your `SPLITWISE_API_KEY` (or consumer key/secret) to git**, do not paste it into shared chats, and do not embed it in a public client.

**5. You accept full responsibility** for any consequences of using this server in connection with your Splitwise account — rate limiting, API key revocation, account warnings, or any enforcement action. If Splitwise objects to your use or your usage exceeds their rate limits, stop using this server.

This section is the maintainer's good-faith summary of the terms — it is not legal advice and does not modify or supersede Splitwise's actual Developer Terms.

## Installation

### Option A -- npx (recommended)

```bash
npx -y splitwise-mcp
```

Add to your Claude config (`.mcp.json` or Claude Desktop config):

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

### Option B -- from source

```bash
git clone https://github.com/chrischall/splitwise-mcp.git
cd splitwise-mcp
npm install
npm run build
```

Add to Claude Desktop config:

- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

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

### Getting your API key

1. Go to [secure.splitwise.com/apps/register](https://secure.splitwise.com/apps/register)
2. Register an app (name and description can be anything)
3. Copy the **API key** from the app detail page

## Credentials

| Env var | Required | Notes |
|---------|----------|-------|
| `SPLITWISE_API_KEY` | Yes | API key from [splitwise.com/apps/register](https://secure.splitwise.com/apps/register) |
| `SPLITWISE_OUTPUT_DIR` | No | Where `sw_get_receipt` writes downloaded receipts (owner-only, mode 0600). Defaults to `~/Downloads/splitwise-mcp`, never the working directory. When set, a per-call `output_dir` must be inside it. |
| `SPLITWISE_INPUT_DIR` | No | The only directory `receipt.path` may read from (`..` and symlinks out of it are refused). Unset — always the case on a hosted server — means receipts are accepted as `upload_id` (hosted) or `base64` only. |
| `MCP_BLOB_BASE_URL` / `MCP_BLOB_SIGNING_KEY` | No | Injected by [mcp-host](https://github.com/chrischall/mcp-host) on the hosted server; they turn on `sw_get_upload_url`. Not set locally. |

## Confirmations

Every Splitwise write (creating, editing or deleting expenses, groups, friends, comments, or your profile) notifies other people, so it asks you to confirm first. A client that can show a confirmation prompt (Claude Code) shows one (unless `MCP_CONFIRM_ELICITATION=off`). On a client that cannot (claude.ai, Claude Desktop), the first call changes nothing and returns a preview of exactly what will be sent plus a `confirmToken`; only a repeat call with that token goes through, and the token is refused if anything in the request changed in between.

To save calls on such a client: **`sw_confirm({confirmToken})`** finishes any previewed write with the token alone (the server kept the arguments, so a receipt's bytes are not sent a second time), and **`sw_batch({ops})`** previews and approves several expense/comment writes at once — e.g. create an expense, then comment on it and attach its receipt with `refs: {"expense_id": "0.expense_id"}`. A batch runs in order and stops at the first failure (no rollback; the result says what was applied).

| variable | default | |
|---|---|---|
| `MCP_CONFIRM_MODE` | `ask-user` | What a write does on a client that cannot show a confirmation prompt (claude.ai, Claude Desktop). `ask-user`: two steps — the first call does nothing and returns a preview plus a token, and the model must get your approval in chat before calling again with it. `auto`: the same two steps, but the model may use the token after reviewing the preview itself. `refuse`: writes are refused on such clients. A client that can show prompts (Claude Code) always gets the real prompt, unless `MCP_CONFIRM_ELICITATION=off`. An unrecognised value is treated as `refuse`. |
| `MCP_CONFIRM_ELICITATION` | `on` | `off` never shows a confirmation prompt, so every client gets the `MCP_CONFIRM_MODE` behaviour. Set it for a client that says it can show prompts but never does (the write hangs — opencode 2.0.x). Any other value is treated as `on`, with a warning on stderr. |
| `MCP_CONFIRM_TTL_SECONDS` | `600` | How long a token stays valid. |
| `MCP_CONFIRM_SECRET` | random per process | Signing key; set it only if tokens must survive a server restart. |

## Available tools

31 tools across 6 domains. All tools are prefixed `sw_`.

### User

| Tool | What it does |
|------|-------------|
| `sw_get_current_user` | Get the authenticated user's profile |
| `sw_healthcheck` | Verify the API key and Splitwise reachability; says which of the two failed |
| `sw_get_user` | Get another user's profile by ID |
| `sw_update_user` | Update the current user's name, locale or default currency (login email and password are not changeable here) |

### Groups

| Tool | What it does |
|------|-------------|
| `sw_list_groups` | List all groups with members |
| `sw_get_group` | Group details including members and balances |
| `sw_create_group` | Create a new group |
| `sw_delete_group` | Soft-delete a group |
| `sw_undelete_group` | Restore a deleted group |
| `sw_add_user_to_group` | Add a user to a group |
| `sw_remove_user_from_group` | Remove a user from a group |

### Friends

| Tool | What it does |
|------|-------------|
| `sw_list_friends` | List all friends |
| `sw_create_friend` | Add a friend by email |
| `sw_delete_friend` | Remove a friendship |

### Expenses

| Tool | What it does |
|------|-------------|
| `sw_list_expenses` | List or search expenses. Splitwise-side filters (group, friend, dates) plus `description_contains`, `include_deleted` (`true`/`false`/`"only"`), `created_by`, `min_cost`/`max_cost` and `category`, paged with `next_cursor`; `view: "rows"` for a one-line-per-expense reconciliation view and `include_comments: true` to see why entries were deleted |
| `sw_get_expense` | Full details of a single expense (compact includes `deleted_by`, `updated_by` and `has_receipt`) |
| `sw_create_expense` | Create an expense — `split_equally`, `split: "equal"` with `paid_by` (someone else paid), or a custom `users` split; `category` by name, or inferred from similar expenses; the preview warns of `possible_duplicates`; optional receipt |
| `sw_update_expense` | Edit an existing expense, or attach/replace its receipt. Refused up front if the expense is deleted |
| `sw_delete_expense` | Soft-delete an expense |
| `sw_undelete_expense` | Restore a deleted expense, then re-read it: returns `post_state`, and fails naming who re-deleted it if it is still deleted |
| `sw_attach_receipt` | Attach or replace the receipt on an existing expense, changing nothing else |
| `sw_get_comments` | Get comments on an expense |
| `sw_create_comment` | Add a comment to an expense |
| `sw_delete_comment` | Delete a comment |

### Confirming

| Tool | What it does |
|------|-------------|
| `sw_confirm` | Finish a previewed write with only its `confirmToken` |
| `sw_batch` | Several expense/comment writes under one preview and one approval; later ops can use an earlier op's new `expense_id` |

### Receipts

| Tool | What it does |
|------|-------------|
| `sw_get_receipt` | Download an expense's receipt image/PDF with the server's credentials. Returns it inline (`inline`), as extracted PDF text (`extract_text`), and/or written to a file |
| `sw_get_upload_url` | Hosted only: a short-lived signed URL to `curl -X PUT` a receipt file to, then pass `receipt: {upload_id, filename}` — no base64 through the conversation. The upload is deleted from the server once Splitwise has the receipt (`upload_deleted` in the reply); a failed write keeps it for a retry |

### Utilities

| Tool | What it does |
|------|-------------|
| `sw_get_notifications` | Recent activity feed |
| `sw_get_categories` | Expense category list |
| `sw_get_currencies` | Supported currency codes |

## Troubleshooting

**"SPLITWISE_API_KEY is required"** -- set the environment variable in your MCP config or a `.env` file.

**Attaching a receipt** -- `sw_create_expense`, `sw_update_expense` and `sw_attach_receipt` take `receipt: { base64, filename, mime_type? }` (works everywhere, including a hosted server) or, on a local server with `SPLITWISE_INPUT_DIR` set, `receipt: { path, filename }` for a file inside that directory. PNG, JPEG, GIF or PDF up to 10 MiB (Splitwise documents no limit); the type is detected from the bytes, and a `mime_type` that disagrees is refused. The confirmation preview shows the file's name, type, size and SHA-256 instead of its contents, and the token is bound to those bytes. After the write the tool checks Splitwise actually stored the file (`receipt.original`) and returns an error naming the expense if it did not. A receipt replaces any receipt already on the expense.

**401 when opening a receipt URL** -- the `receipt.original` / `receipt.large` URLs on an expense are not public; they need the API key. Use `sw_get_receipt` instead of fetching them directly.

**Receipt lands somewhere you can't read it** -- `sw_get_receipt` writes to the *server's* filesystem, which is not the caller's when the server is hosted or containerised. Pass `inline: true` for the bytes (an image block for images, an embedded resource for PDFs) or `extract_text: true` for a PDF's text. With `inline` or `extract_text` and no `output_dir`, nothing is written unless you also pass `write: true`. Pass `write: false` to skip the write in any case; if it fails on its own (read-only filesystem), the call still succeeds and reports `write_error` as long as you asked for content.

**429 rate limit** -- Splitwise has undocumented rate limits. Wait a moment and retry.

**Tools not appearing in Claude** -- go to **Claude Desktop > Settings > Developer** to see connected servers. Make sure you fully quit and relaunched after editing the config.

## Development

```bash
npm test        # tsc typecheck + run the test suite (vitest)
npm run build   # compile TypeScript -> dist/
```

### Project structure

```
src/
  client.ts         Splitwise API client (auth, request handling)
  index.ts          MCP server entry point
  tools/
    user.ts         sw_get_current_user, sw_get_user
    healthcheck.ts  sw_healthcheck
    groups.ts       group CRUD and membership
    friends.ts      friend list and management
    expenses.ts     expense CRUD
    receipts.ts     authenticated receipt download + PDF text extraction
    utilities.ts    notifications, categories, currencies, comments
    _confirm.ts     confirmation gate shared by every write
```

## License

MIT