Gatherings

You set up and run the Gatherings MCP Server to help a group split costs for social events. It exposes an API via the Machine Conversation Protocol so AI assistants can manage gatherings, track expenses, and settle balances with ease.

How to use

Use an MCP client to connect to the server’s standard input/output (stdio) interface. You can create gatherings, add member expenses, compute who owes what, record payments, and close or delete gatherings as balances are settled.

How to install

Prerequisites: Python 3.8 or newer, SQLAlchemy, and the MCP SDK.

Setup steps you follow in order to run the server locally.

# Prerequisites installation (example commands, adjust for your environment)
pip install uv
uv pip install -r requirements.txt

# Optional: set environment variables for your database path and script location
export GATHERINGS_DB_PATH=path/to/database.db
export GATHERINGS_SCRIPT=path/to/gatherings.py

# Optional: clone the project structure (adjust URL as needed)
git clone https://your-repository.git
cd accel

# Install dependencies as described
pip install -r requirements.txt

# Start the MCP server
python gatherings_mcp_server.py

The server runs on stdio, which makes it compatible with MCP protocol clients.

## Architecture

The Gatherings MCP server is built from three core parts: the MCP Server Interface handles the protocol, the Service Layer contains the business logic for managing gatherings, expenses, and payments, and the Data Layer defines the SQLAlchemy ORM models for persistence.

## Data model

Key entities include Gathering (a social event with expenses), Member (a participant), Expense (money spent by a member for the gathering), and Payment (money exchanged to settle balances).

## Examples of what you can do

Create a new gathering with a specified number of members, add expenses for individual members, calculate reimbursements, record payments, rename members, and eventually close or delete a gathering when balances are settled.

## Notes on environment and usage

This server is intended to be run in a local development environment where a client connects via stdio. If you need to customize paths or behavior, you can provide environment variables that point to the database and the script used to initialize or run the server.

## Contributing

Contributions are welcome. If you want to add features or fix issues, submit a pull request with your changes and tests.

## Available tools

### create\_gathering

Create a new gathering with a specified identifier and number of members.

### add\_expense

Add an expense for a specific member within a gathering.

### calculate\_reimbursements

Compute who owes what to whom for a gathering.

### record\_payment

Record a payment by a member or a reimbursement to a member.

### rename\_member

Rename a member within a gathering.

### show\_gathering

Show details of a gathering, including expenses and payment status.

### list\_gatherings

List all gatherings stored in the database.

### close\_gathering

Mark a gathering as closed when settlements are complete.

### delete\_gathering

Delete a gathering and all related data; use force to delete closed gatherings.

### add\_member

Add a new member to an existing gathering.

### remove\_member

Remove a member from a gathering if they have no expenses.