split-bill-mcp

MCP server (stdio) for SplitBill (a Next.js app for splitting bills between friends). It lets an AI agent create bills from split receipts, list and filter bills, update payment statuses, and look up users — all through the SplitBill REST API.

How it works

• The server logs in to SplitBill as a service user (email + password from env) via the NextAuth credentials flow, caches the session cookie, and re-logs in once on 401.

• Money math is cent-exact: receipt positions are split per consumer, remainder cents go to the first consumers, and Σ per-person == total is verified before every create_bill.

• Responses are language-neutral JSON (data) plus a short human summary (English by default, Russian with lang: "ru"). Item names and titles are never translated — they pass through byte-for-byte.

Related MCP server: Splitwise MCP Server

Prereqs

• Node 20+

• A running SplitBill instance, e.g. http://localhost:3000

• A service user registered in SplitBill via /auth/register and confirmed (registration sends a confirmation link; the account must be confirmed before the MCP server can log in as it)

Setup

git clone <this-repo> split-bill-mcp
cd split-bill-mcp
npm install
cp .env.example .env  # then fill in the values below
npm run build

Environment

Missing/invalid vars fail fast at startup with Invalid MCP configuration: VAR: reason.

Connect a client

Build first (npm run build), then pick your client. Replace <path-to-split-bill-mcp> with the directory where you cloned this repo. Secrets can live in the client config or in a .env file next to dist/.

Claude Code — one command (writes to ~/.claude.json):

claude mcp add \
  --env SPLITBILL_BASE_URL=http://localhost:3000 \
  --env SPLITBILL_EMAIL=agent@example.com \
  --env SPLITBILL_PASSWORD=change-me \
  --transport stdio split-bill --scope user \
  -- node <path-to-split-bill-mcp>/dist/index.js

Check with claude mcp list. Or share with the team via .mcp.json (--scope project instead of --scope user).

Codex — one command (writes to ~/.codex/config.toml):

codex mcp add split-bill \
  --env SPLITBILL_BASE_URL=http://localhost:3000 \
  --env SPLITBILL_EMAIL=agent@example.com \
  --env SPLITBILL_PASSWORD=change-me \
  -- node <path-to-split-bill-mcp>/dist/index.js

Check with codex mcp list. Or edit ~/.codex/config.toml by hand:

[mcp_servers.split-bill]
command = "node"
args = ["<path-to-split-bill-mcp>/dist/index.js"]

[mcp_servers.split-bill.env]
SPLITBILL_BASE_URL = "http://localhost:3000"
SPLITBILL_EMAIL = "agent@example.com"
SPLITBILL_PASSWORD = "change-me"

OpenCode — no install command exists, copy this into opencode.json / opencode.jsonc (global ~/.config/opencode/ or project root):

{ "$schema": "https://opencode.ai/config.json",
  "mcp": { "split-bill": {
    "type": "local",
    "command": ["node", "<path-to-split-bill-mcp>/dist/index.js"],
    "environment": {
      "SPLITBILL_BASE_URL": "http://localhost:3000",
      "SPLITBILL_EMAIL": "agent@example.com",
      "SPLITBILL_PASSWORD": "change-me"
    }
  } } }

Pi — pi install only installs Pi extensions, not MCP servers, so a one-liner for our server alone is impossible. Two steps instead: install an MCP client extension, then add the server to its config:

pi install npm:pi-mcp-extension

~/.pi/agent/mcp.json (global) or .pi/mcp.json (project):

{ "mcpServers": { "split-bill": {
  "command": "node",
  "args": ["<path-to-split-bill-mcp>/dist/index.js"],
  "transport": "stdio",
  "lifecycle": "eager",
  "env": {
    "SPLITBILL_BASE_URL": "http://localhost:3000",
    "SPLITBILL_EMAIL": "agent@example.com",
    "SPLITBILL_PASSWORD": "change-me"
  }
} } }

Check with /mcp inside Pi.

Tools

All tools accept an optional lang ("en" default, "ru" for Russian summaries) and return { data, summary, lang }. Users are referenced by email or userId everywhere and resolved automatically (ObjectId passthrough → own email → user search → friends).

create_bill

Create a bill. Two modes:

• mode: "ready_split" — agent already split the receipt: participants: [{ user, items: [{ name, price, priceWithVat?, vat? }], totalSum }], payerId, optional title/description. Item sums are verified per participant (mismatch > 1 cent → VALIDATION_ERROR).

• mode: "raw_receipt" — agent sends receipt positions and who shared what: receipt_items: [{ name, price, priceWithVat?, vat?, consumers: [email|userId], portions? }], payer, optional title/description. The server splits each position across consumers (equally or by portions) and builds the participants itself.

Missing priceWithVat defaults to price, missing vat to false (upstream requires priceWithVat).

Example (raw receipt, agent already figured out who ate what):

{ "mode": "raw_receipt",
  "receipt_items": [
    { "name": "Pizza", "price": 1200, "consumers": ["ann@x.ru", "bob@x.ru"] },
    { "name": "Tea", "price": 300, "consumers": ["ann@x.ru"] }
  ],
  "payer": "ann@x.ru", "title": "Dinner", "lang": "ru" }

→ data: { billId, title, total, per-person amounts/statuses }.

list_bills

List my bills with local filters (upstream has none): status (all|paid|unpaid|pending_confirmation|partial), role (all|creator|payer|debtor), search (title substring), date_from/date_to (must be parseable dates), page/limit. Returns the page plus grouped_by_status counts and a totals summary.

get_bill

billId → full bill with participants, amounts, and payment statuses.

update_payment

billId, participant (email or userId, case-insensitive), status (paid|unpaid|pending_confirmation). Marks one participant's share; returns the refreshed bill.

search_users

query (min 2 chars) → [{ id, name, email }]. Note: upstream search excludes you and your friends — use it to find strangers to add, list_friends for existing friends.

list_friends

Your friends as [{ id, name, email }]. include_requests: true also returns { sent, received } request queues.

get_dashboard_stats

{ totalBills, totalOwed, totalOwing, pendingBills, completedBills }.

Error codes

Dev

npm test        # vitest, 30 tests
npm run dev     # stdio with tsx (needs env set)
npm run typecheck  # covers src + tests
npm run build   # tsc → dist/ (src only)