splitwise-mcp CLAUDE.md

splitwise-mcp

MCP server for Splitwise. Wraps the Splitwise REST API (https://secure.splitwise.com/api/v3.0) and exposes 27 tools to Claude over stdio. Built on @chrischall/mcp-utils (runMcp, createApiClient, readEnvVar, textResult).

Commands

npm run build          # tsc + esbuild bundle → dist/index.js + dist/bundle.js
npm test               # tsc typecheck + vitest run
npm run test:watch     # vitest watch
npm run test:coverage  # tsc typecheck + vitest run --coverage (v8 reporter, no thresholds)

Run locally (requires built dist/):

SPLITWISE_API_KEY=xxx node dist/index.js

Tool naming

All tools are prefixed sw_ (e.g. sw_list_expenses, sw_create_expense).

Architecture

src/
  index.ts        # MCP server entry — calls runMcp() from @chrischall/mcp-utils
                  #   with name/version/banner + the register*Tools array
  client.ts       # SplitwiseClient (createApiClient wrapper) + exported `client`
                  #   singleton; reads SPLITWISE_API_KEY, 1× 2s retry, 30s timeout
  tools/
    user.ts       # sw_get_current_user, sw_get_user, sw_update_user
    groups.ts     # sw_list_groups, sw_get_group, sw_create_group,
                  #   sw_delete_group, sw_undelete_group,
                  #   sw_add_user_to_group, sw_remove_user_from_group
    friends.ts    # sw_list_friends, sw_create_friend, sw_delete_friend
    expenses.ts   # sw_list_expenses, sw_get_expense, sw_create_expense,
                  #   sw_update_expense, sw_delete_expense, sw_undelete_expense
    receipts.ts   # sw_get_receipt — authenticated receipt download,
                  #   inline bytes, and PDF text extraction
    utilities.ts  # sw_get_notifications, sw_get_categories, sw_get_currencies,
                  #   sw_get_comments, sw_create_comment, sw_delete_comment

Each tool file exports a register<Domain>Tools(server, client) function that calls server.registerTool(name, { description, annotations, inputSchema }, handler) (high-level McpServer API with zod schemas). The SplitwiseClient is INJECTED as the second argument rather than imported as a module singleton — a hosted per-user deployment builds one client per authenticated user, which a singleton cannot express. index.ts passes the register functions to runMcp, which builds the McpServer, calls each, and connects the stdio transport.