splitwise

This MCP server integrates Splitwise with an MCP-compatible client, enabling AI agents to manage expenses, groups, friends, and account information through a structured HTTP API. The HTTP server exposes a range of tools (get_current_user, get_user, list_groups, create_group, list_expenses, create_expense, update_expense, delete_expense, list_friends, add_friend, get_currencies, get_categories) that can be invoked via the MCP protocol. Typical usage patterns include initializing the MCP session, querying for user or group data, and performing CRUD operations on expenses and groups. Authentication is enforced via an MCP_AUTH_TOKEN, and requests are routed to the server at the configured host and port (default http://localhost:8080/mcp for local development). You can integrate the server with Claude, ChatGPT-style agents, or other MCP clients by sending JSON-RPC style requests to the /mcp endpoint.

The server requires a Splitwise API key to access your Splitwise data. Once configured, you can instruct the AI to:

• Retrieve current user info or specific user details
• List or create groups and manage their members
• List, view, create, update, or delete expenses with support for filters such as date range or group
• Retrieve friend balances and add new friends by email
• Fetch supported currencies and expense categories for proper data entry and display This enables conversational assistants to manage finances with Splitwise data in a structured, auditable way.

Prerequisites:

• Rust 1.70+ and Cargo installed on your machine
• Splitwise API key (SPLITWISE_API_KEY)
• Optional: for remote access, Docker and docker-compose can be used

Installation steps:

1. Clone the repository and switch to the project directory: git clone https://github.com/marnunez/splitwise-mcp-server.git cd splitwise-mcp-server

2. Create and configure environment variables:

   • Copy the example env file if provided, or create .env with: SPLITWISE_API_KEY=your_api_key_here MCP_AUTH_TOKEN=your_secure_token_here (for HTTP server) PORT=8080 (optional, default 8080) RUST_LOG=info (optional)

3. Build the project (release build): cargo build --release

4. Run the HTTP MCP server (local): cargo run --release --bin splitwise-mcp-http

Alternative: Docker-based deployment (if you prefer containers)

• Ensure Docker and docker-compose are installed
• Prepare an environment file with SPLITWISE_API_KEY and MCP_AUTH_TOKEN
• Use docker-compose to bring up the service as described in the README

Notes:

• If you prefer the stdio server (for Claude Desktop or local MCP clients), you can build and run the splitwise-mcp binary and point clients to its path, with the SPLITWISE_API_KEY exposed in the environment.
• The HTTP server exposes the /mcp endpoint for JSON-RPC style calls. Ensure the MCP_AUTH_TOKEN is provided in the Authorization header as a Bearer token when calling the API.

Tips and common issues:

• Ensure SPLITWISE_API_KEY is valid and has the necessary permissions for your app in secure.splitwise.com/apps
• When deploying remotely, always protect MCP_AUTH_TOKEN and consider running behind HTTPS in production
• If you encounter rate limit issues from the Splitwise API, enable caching or apply request filtering in your client to limit calls
• Use the provided environment variables for configuration rather than embedding keys in code
• For Claude integration, ensure the Claude configuration points to the absolute path of the binary when using the stdio approach, or to the public URL if using the HTTP server
• Logs can be enabled with RUST_LOG=debug during development to diagnose issues; remember to revert to info or warn in production
• If Docker is used, ensure docker-compose ports (default 8080) don’t conflict with existing services
• The API supports standard Create/Read/Update/Delete operations for expenses, groups, and friends; use the tools in the correct sequence to maintain data integrity