Gatherings MCP Server: Automate Splits, Track Balances

What is Gatherings MCP Server: Automate Splits, Track Balances?

Gatherings MCP Server is a TypeScript-based Model Context Protocol (MCP) solution designed to streamline expense tracking and equitable cost distribution for group activities. It leverages a hybrid architecture combining Node.js and Python, though this non-standard setup currently lacks robust error handling and comprehensive test coverage. The server automates financial coordination for events ranging from casual dinners to team projects.

How to Use Gatherings MCP Server: Automate Splits, Track Balances?

Implementation requires three core steps: 1) Install dependencies via package managers, 2) Configure environment variables specifying service endpoints and authentication, and 3) Integrate with platforms like Claude Desktop by deploying the provided YAML configuration template. Development workflows include building with npm scripts and verifying functionality through endpoint testing.

Key Features of Gatherings MCP Server: Automate Splits, Track Balances?

• Expense Automation – Algorithmic distribution of costs based on user-defined parameters
• Multi-Activity Tracking – Concurrent management of multiple event budgets
• Customizable Rulesets – Configure splitting logic (equal shares, proportionate splits, etc.)
• API-First Design – RESTful endpoints for integration with accounting systems

Use Cases of Gatherings MCP Server: Automate Splits, Track Balances?

Typical applications include:
– Divvying up shared expenses for coworking space rentals
– Tracking team travel budgets for remote work groups
– Managing recurring group meal costs in co-living environments
– Allocating project expenses for open-source contributor networks

FAQ from Gatherings MCP Server: Automate Splits, Track Balances?

Why use the Node/Python hybrid architecture?

Legacy component compatibility, though future refactoring is planned

How are disputes resolved?

Administrators can override automated calculations through API adjustments

Does it support cryptocurrency payments?

Base implementation uses fiat currencies, but extension hooks exist for custom payment gateways

Where can I find documentation?

See the GitHub repository for API references and deployment guides

gatherings MCP Server

A Model Context Protocol server for managing gatherings and expense sharing.

This is a TypeScript-based MCP server that helps track expenses and payments for social events, making it easy to calculate reimbursements and settle balances between friends.

Architecture Note

Important : This project uses a non-standard architecture for a Node.js application. The TypeScript MCP server acts as a wrapper around a Python backend implementation. The Node.js server receives MCP requests, translates them to command-line calls to the Python script, and returns the results.

While this architecture works for our current needs, it's not the most efficient or maintainable approach for a production application.

TODO

• Refactor the implementation to use a more standard architecture:
  • Either fully migrate the backend to TypeScript/JavaScript
  • Or implement proper inter-process communication between Node.js and Python components
  • Or replace with a REST API approach where the Python backend provides an API that the MCP server consumes
• Improve error handling between the Node.js and Python components
• Add automated tests for the integration between components

Features

Tools

• create_gathering - Create a new gathering
  • Takes gathering_id and members as required parameters
• add_expense - Add an expense for a member
  • Takes gathering_id, member_name, and amount as required parameters
• calculate_reimbursements - Calculate reimbursements for a gathering
  • Takes gathering_id as a required parameter
• record_payment - Record a payment made by a member
  • Takes gathering_id, member_name, and amount as required parameters
• rename_member - Rename an unnamed member
  • Takes gathering_id, old_name, and new_name as required parameters
• show_gathering - Show details of a gathering
  • Takes gathering_id as a required parameter
• list_gatherings - List all gatherings
• close_gathering - Close a gathering
  • Takes gathering_id as a required parameter
• delete_gathering - Delete a gathering
  • Takes gathering_id as a required parameter, optional force parameter
• add_member - Add a new member to a gathering
  • Takes gathering_id and member_name as required parameters
• remove_member - Remove a member from a gathering
  • Takes gathering_id and member_name as required parameters

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Installation

Configuration

To use with Claude Desktop, add the server config:

{
  "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
    }
  }
}

Configuration Options

• command and args: Specifies how to run the server
• env: Environment variables
  • GATHERINGS_DB_PATH: Path to the database file
  • GATHERINGS_SCRIPT: Path to the Python script for handling gathering operations
• alwaysAllow: List of tools that will be automatically allowed without prompting
• timeout: Maximum execution time in seconds

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.