gatherings

You manage gatherings and expense sharing with a dedicated MCP server written in TypeScript. It acts as a wrapper around a Python backend to track expenses, calculate reimbursements, and settle balances among friends, all accessible via MCP clients.

How to use

You interact with the server through an MCP client to create gatherings, add expenses, calculate reimbursements, record payments, and manage members. The server exposes a complete set of operations that you can invoke to keep track of who owes whom and how much has been paid.

To perform actions, send commands that correspond to the available tools, such as creating a gathering, adding expenses for members, and reconciling balances. The server also supports showing details of a gathering, listing all gatherings, renaming unnamed members, and removing or adding members as your event evolves. All communications occur through the MCP protocol so you can integrate it with your existing MCP client workflow.

How to install

Prerequisites you need before starting: You should have Node.js and npm installed on your system. Ensure Python is available for the Python backend if you plan to use that path directly.

Install dependencies for the server package and build the project so you can run it locally in development or production environments.

Run the development workflow to enable auto-rebuilds while you work.

# Install dependencies
npm install

# Build the MCP server
npm run build

# Development with auto-rebuild
npm run watch

Configuration and usage notes

Configure the MCP client to connect to the gatherings server by adding an MCP server entry. The example config shows a local stdio server that runs a Node.js wrapper and points to the Python backend script for operations.

{
  "mcpServers": {
    "gatherings": {
      "command": "node",
      "args": ["/path/to/gatherings-server/build/index.js"],
      "env": {
        "GATHERINGS_DB_PATH": "gatherings.db",
        "GATHERINGS_SCRIPT": "/path/to/gatherings-server/gatherings.py"
      },
      "disabled": false,
      "autoApprove": [],
      "alwaysAllow": [
        "create_gathering",
        "add_expense",
        "calculate_reimbursements",
        "record_payment",
        "rename_member", 
        "show_gathering",
        "list_gatherings",
        "close_gathering",
        "delete_gathering",
        "add_member",
        "remove_member"
      ],
      "timeout": 300
    }
  }
}

Developer notes

Debugging MCP servers that communicate over stdio can be challenging. You can use the MCP Inspector for debugging and tool access. Start the inspector to obtain a debugging URL you can open in your browser.

npm run inspector

Available tools

create_gathering

Create a new gathering by providing a gathering_id and initial member list.

add_expense

Add an expense entry for a member within a specific gathering.

calculate_reimbursements

Compute reimbursements for a gathering to settle balances.

record_payment

Record a payment made by a member toward a gathering's expenses.

rename_member

Rename an unnamed member within a gathering.

show_gathering

Show full details for a specific gathering.

list_gatherings

List all existing gatherings.

close_gathering

Close a gathering to prevent further changes.

delete_gathering

Delete a gathering, with an option to force delete.

add_member

Add a new member to a gathering.

remove_member

Remove a member from a gathering.