SplitEase MCP Server

MCP (Model Context Protocol) server for the SplitEase shared expense tracking API. Provides 11 purpose-driven tools optimized for AI assistants.

Connector Setup Guide

For step-by-step setup with ChatGPT Apps and Claude custom connectors, see:

• CONNECTORS_GUIDE.md

Installation

bun install

Configuration

Required:

• SPLITEASE_API_URL: SplitEase backend base URL

Stdio mode:

• API_KEY (or SPLITEASE_API_KEY): SplitEase API key or OAuth bearer token

HTTP mode for OAuth connector clients:

• MCP_HTTP_PORT: Enable Streamable HTTP mode
• MCP_PUBLIC_BASE_URL: Public MCP base URL (used in OAuth resource metadata)
• MCP_OAUTH_AUTHORIZATION_SERVER: OAuth issuer URL (usually your backend base URL)

MCP Client Configuration

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "splitease": {
      "command": "bunx",
      "args": ["@themuneebh-oss/hisab-mcp"],
      "env": {
        "SPLITEASE_API_URL": "http://localhost:3000",
        "API_KEY": "your_splitease_api_key"
      }
    }
  }
}

Claude Code

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "splitease": {
      "command": "bunx",
      "args": ["@themuneebh-oss/hisab-mcp"],
      "env": {
        "SPLITEASE_API_URL": "http://localhost:3000",
        "API_KEY": "your_splitease_api_key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "splitease": {
      "command": "bunx",
      "args": ["@themuneebh-oss/hisab-mcp"],
      "env": {
        "SPLITEASE_API_URL": "http://localhost:3000",
        "API_KEY": "your_splitease_api_key"
      }
    }
  }
}

VS Code with Continue

Add to .continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "bunx",
          "args": ["@themuneebh-oss/hisab-mcp"],
          "env": {
            "SPLITEASE_API_URL": "http://localhost:3000",
            "API_KEY": "your_splitease_api_key"
          }
        }
      }
    ]
  }
}

Generic MCP Client

For any MCP-compatible client, use this configuration:

{
  "name": "splitease",
  "transport": "stdio",
  "command": "bunx",
  "args": ["@themuneebh-oss/hisab-mcp"],
  "env": {
    "SPLITEASE_API_URL": "http://localhost:3000",
    "API_KEY": "your_splitease_api_key"
  }
}

Available Tools

Groups

| Tool | Description | |------|-------------| | get_groups_overview | List all groups with balance summaries | | get_group_context | Full context: members, balances, recent expenses, stats | | manage_group | Create/rename/delete groups, add/remove members |

Expenses

| Tool | Description | |------|-------------| | add_expense | Add expense with smart defaults (requires recent get_group_context + confirmWithUser=true) | | add_quick_expense | Ultra-simple expense add (same safety requirement as add_expense) | | search_expenses | Find expenses by query, month, amount range, payer | | update_expense | Modify existing expense | | delete_expense | Remove expense (shows balance impact) |

Settlements

| Tool | Description | |------|-------------| | who_owes_what | Plain-English debt summary with suggested settlements | | settle_up | Record settlement payment between users | | get_spending_insights | Monthly trends and spending analysis |

Example Workflow

1. get_groups_overview()
2. get_group_context(groupId: "...")
3. Ask user to confirm this is a new expense (not a duplicate)
4. add_quick_expense(groupId: "...", description: "Dinner", amount: 45.00, confirmWithUser: true)
5. who_owes_what(groupId: "...")
6. settle_up(groupId: "...", fromUserId: "...", toUserId: "...", amount: 15.00)

Development

# Run with hot reload
bun --hot index.ts

# Test server startup
SPLITEASE_API_URL=http://localhost:3000 API_KEY=your_splitease_api_key bun run index.ts

HTTP Transport (Streamable HTTP on /sse)

This server can also run as an HTTP MCP server using the MCP Streamable HTTP transport (protocol 2025-11-25). When enabled, it exposes:

• MCP endpoint: /sse (default; supports GET/POST/DELETE)
• OAuth resource metadata: /.well-known/oauth-protected-resource

MCP_HTTP_PORT=3001 \
MCP_PUBLIC_BASE_URL=https://your-mcp.example.com \
MCP_OAUTH_AUTHORIZATION_SERVER=https://your-api.example.com \
SPLITEASE_API_URL=http://localhost:3000 \
bun run index.ts

In HTTP mode:

• Preferred for connectors: Authorization: Bearer <oauth_access_token>
• Legacy/manual clients: x-api-key is still accepted
• Unauthenticated requests receive 401 with WWW-Authenticate: Bearer ... resource_metadata=".../.well-known/oauth-protected-resource"

Notes for Railway/hosted deploys:

• The platform usually sets PORT dynamically; this server will fall back to PORT if MCP_HTTP_PORT is not set.
• If you don't set MCP_HTTP_HOST, the server binds to 0.0.0.0 when PORT is present (so it's reachable externally).

Defaults:

• MCP_HTTP_HOST=127.0.0.1
• MCP_HTTP_PATH=/sse

Tool Schemas

get_groups_overview

No parameters required.

get_group_context

{
  "groupId": "string (required) - Group ID",
  "month": "string (optional) - Filter by month (YYYY-MM)"
}

manage_group

{
  "action": "create | rename | addMember | removeMember | delete",
  "groupId": "string (optional) - Required for all actions except create",
  "name": "string (optional) - Required for create/rename",
  "userId": "string (optional) - Required for addMember/removeMember"
}

add_expense

{
  "groupId": "string (required)",
  "description": "string (required)",
  "amount": "number (required)",
  "paidBy": "[{userId, amount}] (optional) - Defaults to current user",
  "splitAmong": "[{userId, amount?}] (optional) - Defaults to all members",
  "splitMode": "equal | custom (optional, default: equal)",
  "confirmWithUser": "boolean (required in practice) - true only after get_group_context + explicit user confirmation",
  "date": "string (optional, default: today)",
  "notes": "string (optional)"
}

add_quick_expense

{
  "groupId": "string (required)",
  "description": "string (required)",
  "amount": "number (required)",
  "confirmWithUser": "boolean (required in practice) - true only after get_group_context + explicit user confirmation"
}

search_expenses

{
  "groupId": "string (required)",
  "query": "string (optional) - Search in description",
  "month": "string (optional) - YYYY-MM format",
  "minAmount": "number (optional)",
  "maxAmount": "number (optional)",
  "payerId": "string (optional)"
}

update_expense

{
  "groupId": "string (required)",
  "expenseId": "string (required)",
  "description": "string (optional)",
  "amount": "number (optional)",
  "date": "string (optional)",
  "notes": "string (optional)",
  "payers": "[{userId, amount}] (optional)",
  "splits": "[{userId, amount}] (optional)",
  "splitMode": "equal | custom (optional)"
}

delete_expense

{
  "groupId": "string (required)",
  "expenseId": "string (required)"
}

who_owes_what

{
  "groupId": "string (required)"
}

settle_up

{
  "groupId": "string (required)",
  "fromUserId": "string (required) - Who is paying",
  "toUserId": "string (required) - Who is receiving",
  "amount": "number (required)"
}

get_spending_insights

{
  "groupId": "string (required)",
  "userId": "string (optional) - Analyze specific user",
  "period": "3months | 6months | 12months | all (optional, default: 6months)"
}