Expense Splitter MCP Server

A Model Context Protocol (MCP) server for managing shared expenses between groups. Built with TypeScript, MongoDB, and clean architecture principles.

Instead of manually calculating who owes whom, the server computes optimized settlements using a debt simplification algorithm.

Use Cases

• Friends trip expenses

• Flatmate shared bills

• Carpool cost sharing

• Office lunch splits

• Vacation planning

Related MCP server: Gatherings MCP Server

Setup

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Start production
npm start

# Open inspector
npm run inspector

MCP Client Configuration

Claude Desktop / Cursor / VS Code

Add to your MCP settings configuration:

{
  "servers": {
    "expense-splitter": {
      "command": "node",
      "args": ["/absolute/path/to/expense-splitter-mcp/dist/index.js"],
      "env": {
        "MONGODB_URI": "mongodb://test/expense-splitter"
      }
    }
  }
}

SSE Transport

Set TRANSPORT=sse in .env, then start the server:

npm start

Connect your MCP client to http://localhost:3001/sse.

Available Tools (19)

Group Management

Member Management

Expense Management

Balances & Settlements

History & Reports

Import / Export

Split Types

Debt Simplification Algorithm

The server uses a greedy algorithm to minimize the number of transactions:

1. Compute net balance for each member (received - paid)

2. Separate into creditors (positive) and debtors (negative)

3. Sort both lists descending

4. Match biggest creditor with biggest debtor

5. Transfer the minimum of both amounts

6. Repeat until all debts are settled

Complexity: O(n log n)

Example

Raw debts from 4 expenses could result in 6+ individual debts, but the algorithm simplifies them to just 3 transactions.

Complete Example: Goa Trip

Here's a real end-to-end walkthrough showing how an AI assistant uses the Expense Splitter MCP server.

Step 1: Create the Group

User: "Create an expense group called Goa Trip."

AI calls create_group:

{ "name": "Goa Trip", "currency": "INR" }

Response:

{ "id": "grp_abc123", "name": "Goa Trip", "currency": "INR" }

Step 2: Add Members

User: "Add Alice, Bob, Charlie and David."

AI calls add_member 4 times:

{ "groupId": "grp_abc123", "name": "Alice" }
{ "groupId": "grp_abc123", "name": "Bob" }
{ "groupId": "grp_abc123", "name": "Charlie" }
{ "groupId": "grp_abc123", "name": "David" }

Step 3: Hotel Expense (Equal Split)

User: "Alice paid ₹12,000 for the hotel. Split it equally."

AI calls add_expense:

{
  "groupId": "grp_abc123",
  "description": "Hotel",
  "amount": 12000,
  "paidBy": "Alice",
  "participants": ["Alice", "Bob", "Charlie", "David"],
  "splitType": "equal"
}

Each person owes ₹3,000. Balances:

Step 4: Dinner (Equal Split)

User: "Bob paid ₹3,200 for dinner."

AI calls add_expense:

{
  "groupId": "grp_abc123",
  "description": "Dinner",
  "amount": 3200,
  "paidBy": "Bob",
  "participants": ["Alice", "Bob", "Charlie", "David"],
  "splitType": "equal"
}

Each owes ₹800. Updated balances:

Step 5: Fuel (Exact Split)

User: "Charlie paid ₹2,400 for fuel. Bob owes ₹1,200 and David owes ₹1,200."

AI calls add_expense:

{
  "groupId": "grp_abc123",
  "description": "Fuel",
  "amount": 2400,
  "paidBy": "Charlie",
  "participants": ["Bob", "David"],
  "splitType": "exact",
  "splits": { "Bob": 1200, "David": 1200 }
}

Balances:

Step 6: Beach Activities (Equal Split, Subset)

User: "David paid ₹4,000 for beach activities. Split between Alice and David."

AI calls add_expense:

{
  "groupId": "grp_abc123",
  "description": "Beach Activities",
  "amount": 4000,
  "paidBy": "David",
  "participants": ["Alice", "David"],
  "splitType": "equal"
}

Balances:

Step 7: Check Balances

User: "Who owes whom?"

AI calls get_balances:

{ "groupId": "grp_abc123" }

Response:

Alice    +₹6,200  (is owed money)
Bob      -₹1,800  (owes money)
Charlie  -₹1,400  (owes money)
David    -₹3,000  (owes money)

Step 8: Simplify Debts

User: "Simplify the debts."

AI calls settle_debts:

{ "groupId": "grp_abc123" }

Response:

{
  "transactions": [
    { "from": "David", "to": "Alice", "amount": 3000 },
    { "from": "Bob", "to": "Alice", "amount": 1800 },
    { "from": "Charlie", "to": "Alice", "amount": 1400 }
  ]
}

Only 3 transactions settle the entire trip:

David   → Alice  ₹3,000
Bob     → Alice  ₹1,800
Charlie → Alice  ₹1,400

Step 9: Record a Payment

User: "Bob paid Alice ₹1,800."

AI calls record_settlement:

{
  "groupId": "grp_abc123",
  "from": "Bob",
  "to": "Alice",
  "amount": 1800,
  "note": "UPI transfer for trip settlement"
}

Step 10: Updated Balances

User: "Show balances again."

AI calls get_balances:

Alice    +₹4,400
Bob       ₹0 ✅
Charlie  -₹1,400
David    -₹3,000

Step 11: Trip History

User: "Show trip history."

AI calls get_history:

✓ Hotel            ₹12,000  (paid by Alice)
✓ Dinner            ₹3,200  (paid by Bob)
✓ Fuel              ₹2,400  (paid by Charlie)
✓ Beach Activities  ₹4,000  (paid by David)
✓ Settlement: Bob → Alice ₹1,800

Step 12: Trip Summary

User: "Give me a summary."

AI calls get_group_summary:

{
  "group": "Goa Trip",
  "members": 4,
  "expenses": 4,
  "totalSpent": 21600,
  "largestExpense": { "description": "Hotel", "amount": 12000 },
  "topSpender": "Alice",
  "outstanding": 4400
}

Summary:

Goa Trip Summary
────────────────
Members:            4
Expenses:           4
Total Spent:        ₹21,600
Largest Expense:    Hotel (₹12,000)
Top Spender:        Alice
Outstanding Amount: ₹4,400

Complete Tool Flow