money-split-mcp

A remote, multi-user MCP server for splitting group expenses (Splitwise-lite). Each user registers an account by email, gets an API key, and uses that key to create groups, add members by email, log expenses, and see who owes whom — all through an MCP client (Claude Desktop, claude.ai connectors, etc.).

How it works

• POST /register is a plain REST endpoint (not an MCP tool) that creates a user and returns a one-time API key.

• Every other call goes through POST /mcp (MCP Streamable HTTP) with Authorization: Bearer <api_key>. The server is stateless: each request resolves the caller from their API key and builds a fresh, user-scoped set of tools.

• Data (users, groups, expenses, shares, settlements) lives in Postgres via Prisma.

Related MCP server: Gatherings MCP Server

Local setup

1. Copy .env.example to .env and adjust DATABASE_URL if needed.

2. Get a local Postgres running, matching .env's DATABASE_URL (moneysplit/moneysplit/db moneysplit on localhost:5432):

   • Native install: sudo apt-get install -y postgresql postgresql-contrib, then:

     sudo -u postgres psql -c "CREATE USER moneysplit WITH PASSWORD 'moneysplit';"
     sudo -u postgres psql -c "CREATE DATABASE moneysplit OWNER moneysplit;"

   • Docker (if available): docker compose up -d

3. Install deps and run the first migration:

   npm install
   npm run prisma:migrate

4. Start the dev server: npm run dev (listens on http://localhost:3000 by default).

5. Run the unit tests any time: npm test (covers the split/balance math, no DB needed).

Manually testing the full flow

Register two users:

curl -s localhost:3000/register -H 'content-type: application/json' \
  -d '{"email":"alice@example.com","name":"Alice"}'
curl -s localhost:3000/register -H 'content-type: application/json' \
  -d '{"email":"bob@example.com","name":"Bob"}'

Each response includes an apiKey — save both, they're never shown again.

Then drive the MCP tools with the MCP Inspector:

npx @modelcontextprotocol/inspector

Connect it to http://localhost:3000/mcp (Streamable HTTP transport) with header Authorization: Bearer <alice's apiKey>, then call tools in order:

1. create_group { "name": "Trip to Goa" } → note the returned group id

2. add_member_to_group { "group_id": "...", "email": "bob@example.com" }

3. add_expense { "group_id": "...", "description": "Hotel", "amount": 100 } (defaults: paid by Alice, split evenly across all members)

4. get_balances { "group_id": "..." } → Alice should show +50, Bob -50, with a suggested settlement of Bob paying Alice 50.

5. Reconnect the Inspector with Bob's API key and call settle_up { "group_id": "...", "to_email": "alice@example.com", "amount": 50 }, then get_balances again to confirm both are back to 0.

Deploying to Render

This repo includes a render.yaml Blueprint that provisions a Postgres database and a Node web service together.

1. Push this repo to GitHub.

2. In the Render dashboard: New > Blueprint, point it at the repo — it will read render.yaml and create both the money-split-db database and the money-split-mcp web service, wiring DATABASE_URL automatically.

3. The web service's build command runs npx prisma migrate deploy after compiling, keeping the schema in sync on every deploy. (Render's free plan doesn't support the separate preDeployCommand step, so it's folded into the build instead.)

4. Once deployed, verify:

   curl https://<your-service>.onrender.com/health

Note: Render's free Postgres plan expires after a fixed trial period — check current Render pricing before relying on it long-term; swap in any external Postgres (e.g. Neon, Supabase) by just changing DATABASE_URL if needed.

Using it from an MCP client

1. Register a real account against the deployed URL:

   curl -s https://<your-service>.onrender.com/register -H 'content-type: application/json' \
     -d '{"email":"you@example.com","name":"Your Name"}'

2. Add it as a remote MCP server in your client.

   Claude Code (CLI) — add it at local scope (not committed to git) with the key pulled from an env var, since .mcp.json would otherwise be shared/committed:

   export MONEY_SPLIT_API_KEY=<your apiKey>
   
   claude mcp add --transport http money-split https://<your-service>.onrender.com/mcp \
     --header "Authorization: Bearer \${MONEY_SPLIT_API_KEY}"

   Claude Desktop — add to its config:

   {
     "mcpServers": {
       "money-split": {
         "url": "https://<your-service>.onrender.com/mcp",
         "headers": { "Authorization": "Bearer <your apiKey>" }
       }
     }
   }

   (Check your specific client's docs for the exact key names it expects for a remote Streamable HTTP server with custom headers — some clients configure this through a UI instead of raw JSON.)

3. Each group member registers their own account and adds the server with their own key — that's what ties MCP activity back to "their" groups and balances.

4. From inside the client: "create a group called Goa Trip", "add bob@example.com to it", "log a ₹3000 hotel expense split evenly", "who owes whom in the Goa Trip group?".