Gatherings MCP Python

🚀 Gatherings MCP Server

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

🚀 Quick Start

The Gatherings MCP Server provides an API that allows AI assistants to interact with the Gatherings application via the Machine Conversation Protocol. This enables AI systems to help users manage social events, outings, or shared expenses for any gathering.

✨ Features

• Create and manage gatherings with multiple members
• Add expenses for specific members
• Calculate fair reimbursements
• Record payments and reimbursements
• Generate detailed payment summaries
• Add/remove members from a gathering
• Rename members at any time

📦 Installation

Prerequisites

• Python 3.8+
• SQLAlchemy
• MCP SDK

Setup

1. Clone this repository:

   git clone https://your-repository.git
   cd accel
   

2. Install the required dependencies:

   pip install -r requirements.txt
   

3. Set environment variables (optional):

   # Customize the database location
   export GATHERINGS_DB_PATH=path/to/database.db
   
   # Customize the script location
   export GATHERINGS_SCRIPT=path/to/gatherings.py
   

💻 Usage Examples

Basic Usage

python gatherings_mcp_server.py

The server runs on standard input/output, making it compatible with MCP protocol clients.

📚 Documentation

Dependency Management

This project uses uv for Python dependency management instead of pip. This change is due to the dependency requirements of the Model Context Protocol Python SDK.

Ensure you have uv installed or install it via the following command:

pip install uv

To install the project dependencies:

uv pip install -r requirements.txt

📄 API Reference

The MCP server exposes the following tools:

create_gathering(gathering_id: str, members: int)

Create a new gathering with the specified number of members.

add_expense(gathering_id: str, member_name: str, amount: float)

Add an expense for a member in the gathering.

calculate_reimbursement(gathering_id: str)

Calculate the reimbursement amount for the gathering.

record_payment(gathering_id: str, payer: str, amount: float)

Record a payment made by a member.

generate_summary(gathering_id: str)

Generate a payment summary for the gathering.

add_member(gathering_id: str, member_name: str)

Add a new member to the gathering.

remove_member(gathering_id: str, member_name: str)

Remove a specified member from the gathering.

rename_member(gathering_id: str, old_name: str, new_name: str)

Rename a member in the gathering.

🤝 Contribution

Contributions are welcome! Please feel free to submit a Pull Request.