JUHE API Marketplace
abutbul avatar
MCP Server

Gatherings MCP Server

A Model Context Protocol server that helps track expenses and calculate reimbursements for social events, making it easy to settle balances between friends.

0
GitHub Stars
8/23/2025
Last Updated
MCP Server Configuration
1{
2 "name": "gatherings",
3 "command": "node",
4 "args": [
5 "/path/to/gatherings-server/build/index.js"
6 ],
7 "env": {
8 "GATHERINGS_DB_PATH": "gatherings.db",
9 "GATHERINGS_SCRIPT": "/path/to/gatherings-server/gatherings.py"
10 },
11 "disabled": false,
12 "autoApprove": [],
13 "alwaysAllow": [
14 "create_gathering",
15 "add_expense",
16 "calculate_reimbursements",
17 "record_payment",
18 "rename_member",
19 "show_gathering",
20 "list_gatherings",
21 "close_gathering",
22 "delete_gathering",
23 "add_member",
24 "remove_member"
25 ],
26 "timeout": 300
27}
JSON27 lines

README Documentation

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:

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.

Quick Install

Quick Actions

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source