Expense Splitter

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

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

You can connect to the Expense Splitter MCP server in two ways.

Option 1: Use the hosted server (recommended)

If you just want to use the server, no local setup is required.

Simply configure your MCP client to connect to the hosted Streamable HTTP endpoint:

{
  "servers": {
    "expense-splitter": {
      "type": "http",
      "url": "https://expense-splitter-mcp.onrender.com/mcp"
    }
  }
}

Note: The server is already running on Render, so you only need to provide the URL.

For VS Code, place the same configuration in .vscode/mcp.json.

---

Option 2: Run the server locally

If you want to run your own instance, you have two transport options.

A. stdio

With stdio, the MCP client starts the server for you.

Configure your client as follows:

{
  "servers": {
    "expense-splitter": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "MONGODB_URI": "mongodb://test/expense-splitter"
      }
    }
  }
}

When the MCP client starts, it automatically launches:

node dist/index.js

No manual server startup is required.

---

B. Streamable HTTP

With Streamable HTTP, the server must already be running before the MCP client connects.

1. Enable HTTP transport:

TRANSPORT=http

2. Start the server:

npm start

3. Configure your MCP client:

{
  "servers": {
    "expense-splitter": {
      "type": "http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

The MCP client connects to the running server at http://localhost:3001/mcp.

Why doesn't the Streamable HTTP configuration include a command?

Because, unlike stdio, the MCP client does not start the server. It simply connects to an existing HTTP endpoint. You are responsible for starting the server (npm start), or you can use the hosted instance on Render.

Available Tools (19)

Group Management

Tool	Description
create_group	Create a new expense group (with optional currency)
list_groups	List all expense groups
get_group	Get group details with members
rename_group	Rename a group
delete_group	Soft-delete a group and all associated data

Member Management

Tool	Description
add_member	Add a member (with optional email/nickname)
remove_member	Remove a member (only if no expenses or settlements)
list_members	List all members in a group

Expense Management

Tool	Description
add_expense	Add expense with equal/exact/percentage split
update_expense	Update an existing expense
delete_expense	Soft-delete an expense
search_expenses	Search with filters (description, payer, date, etc.)

Balances & Settlements

Tool	Description
get_balances	Get net balance for each member
settle_debts	Compute optimized settlement plan
record_settlement	Record a payment between members (with optional note)

History & Reports

Tool	Description
get_history	Chronological log of expenses & settlements
get_group_summary	Summary stats (total, top spender, etc.)

Import / Export

Tool	Description
export_group	Export group data (JSON/CSV)
import_group	Import group from JSON data

Split Types

Type	Description	Example
equal	Amount divided equally among participants	₹12,000 ÷ 4 = ₹3,000 each
exact	Specific amounts per participant	Bob: ₹1,200, David: ₹1,200
percentage	Percentage-based split	Alice: 60%, Bob: 40%

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:

Member	Balance
Alice	+9,000
Bob	-3,000
Charlie	-3,000
David	-3,000

---

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:

Member	Balance
Alice	+8,200
Bob	-600
Charlie	-3,800
David	-3,800

---

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:

Member	Balance
Alice	+8,200
Bob	-1,800
Charlie	-1,400
David	-5,000

---

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:

Member	Balance
Alice	+6,200
Bob	-1,800
Charlie	-1,400
David	-3,000

---

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

#	Action	Tool Used
1	Create Goa Trip	create_group
2	Add 4 members	add_member × 4
3	Alice paid hotel	add_expense
4	Bob paid dinner	add_expense
5	Charlie paid fuel	add_expense
6	David paid beach	add_expense
7	Show balances	get_balances
8	Simplify debts	settle_debts
9	Bob paid Alice	record_settlement
10	Updated balances	get_balances
11	Show history	get_history
12	Trip summary	get_group_summary