# splitwise-mcp

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for [Splitwise](https://splitwise.com) — manage shared expenses directly from Claude, Cursor, or any MCP-compatible AI assistant.

No well-maintained Splitwise MCP existed. This one does.

---

## Tools

| Tool | Description |
|------|-------------|
| `get_expenses` | List expenses — filter by group, friend, date range |
| `get_expense` | Get a single expense by ID |
| `create_expense` | Create a new expense with per-user splits |
| `delete_expense` | Delete an expense by ID |
| `get_friends` | List all friends with IDs and balances |
| `get_groups` | List all groups with members and debts |
| `get_friend_balances` | Pre-computed net balance summary (who owes you, who you owe) |
| `get_current_user` | Get your Splitwise user ID |

---

## Setup

### Option A — API Key (simplest)

1. Go to [splitwise.com/apps](https://secure.splitwise.com/apps)
2. Register an app (or use existing) → copy the **API Key**
3. Set env var: `SPLITWISE_API_KEY=your_api_key`

### Option B — OAuth 1.0

1. Go to [splitwise.com/apps](https://secure.splitwise.com/apps) → register an app
2. Copy **Consumer Key** and **Consumer Secret**
3. Complete the OAuth 1.0 flow to get an access token and secret
4. Set env vars:
```
SPLITWISE_CONSUMER_KEY=your_consumer_key
SPLITWISE_CONSUMER_SECRET=your_consumer_secret
SPLITWISE_ACCESS_TOKEN=your_access_token
SPLITWISE_ACCESS_TOKEN_SECRET=your_access_token_secret
```

---

## Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

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

Restart Claude Desktop — you'll see the Splitwise tools available.

---

## Example prompts

- *"What do I owe on Splitwise?"*
- *"Show me all expenses from last month"*
- *"Add a $60 dinner split equally between me and Alice"*
- *"Which of my friends owes me the most?"*
- *"Show me all expenses in my Roommates group"*

---

## Local development

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

# Run with your API key
SPLITWISE_API_KEY=your_key node dist/index.js
```

---

## License

MIT