Gatherings MCP

🚀 Gathering MCP Server

A TypeScript-based MCP server for managing gatherings and splitting expenses.

This server helps track expenditures and payments in social activities, making it easy to calculate reimbursements and settle balances among friends.

📋 Note: Architecture

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

Although this architecture currently meets our needs, it is not the most efficient or maintainable approach for a production application.

📝 To-Do List

• Refactor the implementation to a more standard architecture:
  • Completely migrate the backend to TypeScript/JavaScript
  • Or implement proper inter-process communication between the Node.js and Python components
  • Or replace it with a REST API, where the Python backend provides the API used by the MCP server
• Improve error handling between the Node.js and Python components
• Add automated tests for the integration between components
• Optimize the Dockerfile

✨ Features

🛠️ Tools

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

🚧 Development

Install dependencies:

npm install

Build the server:

npm run build

Develop with automatic rebuild:

npm run watch

📦 Installation

⚙️ Configuration

To use with Claude Desktop, add the following server configuration:

{
  "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: Specify how to run the server
• env: Environment variables
  • GATHERINGS_DB_PATH: Path to the database file
  • GATHERINGS_SCRIPT: Path to the Python script that handles gathering operations
• alwaysAllow: List of tools to automatically allow without prompting
• timeout: Maximum execution time (in seconds)

🐞 Debugging

Since the MCP server communicates via stdio, debugging can be difficult. We recommend using MCP Inspector, which is available as a package script:

npm run inspector

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