Gatherings MCP Server

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
• Optimise Dockerfile

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:

Build the server:

For development with auto-rebuild:

Installation

Configuration

To use with Claude Desktop, add the server config:

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:

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