splitwise-mcp

HiFinance-pvt/splitwise-mcp

3.2

If you are the rightful owner of splitwise-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This document provides a comprehensive overview of deploying a remote Model Context Protocol (MCP) server on Cloudflare Workers without authentication.

Splitwise MCP Server 🪙🤝

Cloudflare Workers

A lightweight Model Context Protocol (MCP) server that provides Splitwise integrations and tools for managing users, groups, friends, expenses and notifications. This project is built for Cloudflare Workers using Durable Objects and exposes OAuth endpoints to authorize Splitwise access.

🚀 Deployed Server

Live URL: https://splitwise-mcp.hifi.click

  • MCP Endpoint: https://splitwise-mcp.hifi.click/sse
  • OAuth Authorization: https://splitwise-mcp.hifi.click/authorize

💡 Ready to use: The server is deployed and ready for integration with Claude Desktop, Cursor, or any MCP-compatible client.

Table of Contents

About

Splitwise MCP is an MCP server implementation designed to act as a bridge between an MCP client (such as an agent) and Splitwise APIs. It exposes a set of MCP tools to perform actions like creating expenses, managing groups, and retrieving notifications. This repository uses Cloudflare Workers (Wrangler), Durable Objects and a small OAuth provider for Splitwise.

Features ✨

  • Durable Object based MCP agent (MyMCP) for stateful server behavior
  • OAuth endpoints for Splitwise integration
  • A rich set of MCP tools for user, group, friend, expense and notification management
  • TypeScript, Biome for formatting/linting, and Wrangler for local dev & deploy

🚨 Deployed-first recommendation: This project is intended to be used from a public, deployed MCP server for real integrations (Claude, Cursor, agents). Use local (wrangler dev) only for development and testing. The README below focuses on the deployed-server workflow.

Quick Start 🚀

Prerequisites

  • Node.js (16+ recommended)
  • pnpm (because this repo contains a pnpm-lock.yaml) or npm/yarn
  • Wrangler (Cloudflare CLI)

Installation

# Clone the repository
git clone <your-repo-url>
cd splitwise-mcp-server

# Install dependencies
pnpm install

Useful Scripts

From package.json:

  • pnpm dev — run wrangler dev locally
  • pnpm start — alias to wrangler dev
  • pnpm deploy — run wrangler deploy to publish to Cloudflare

Run Locally (Development)

pnpm dev
# or
pnpm start

Deploy to Cloudflare

pnpm deploy

Environment & Configuration 🔐

The server expects several environment variables (set these as Wrangler secrets or in your Cloudflare environment):

  • SPLITWISE_CONSUMER_KEY — Splitwise API consumer key
  • SPLITWISE_CONSUMER_SECRET — Splitwise API consumer secret
  • SPLITWISE_CALLBACK_URL — OAuth callback URL for Splitwise
  • BACKEND_URL — optional backend URL used by the server
  • PHONE_NUMBER — phone number used by the validate tool (formatted optionally with a +)

Setting Secrets with Wrangler

wrangler secret put SPLITWISE_CONSUMER_KEY
wrangler secret put SPLITWISE_CONSUMER_SECRET
wrangler secret put SPLITWISE_CALLBACK_URL

Durable Object Binding

The Durable Object class is MyMCP, and in wrangler.jsonc a binding called MCP_OBJECT is defined. Wrangler will use this when you run local development and when deploying.

Local Development

Run the development server:

pnpm dev

The server will be available at http://127.0.0.1:8787 (or the URL shown by Wrangler).

Endpoints & OAuth Flow 🔁

This project mounts an OAuth provider and MCP API handler with the following routes (as configured in src/index.ts):

  • POST /sse — MCP API handler (server mounted here via MyMCP.mount("/sse")) — primary API endpoint for MCP traffic
  • GET /authorize — Start OAuth authorization with Splitwise
  • POST /register — Client registration endpoint
  • POST /token — Token endpoint for exchanging authorization grants

Note: OAuth flows are interactive and usually start by visiting the /authorize URL in a browser.

Available MCP Tools 🧰

The MCP server registers many tools for interacting with Splitwise. Key ones include:

Server Tools

  • about — Returns package/about information
  • validate — Basic server validation (returns phone number formatting)

User Tools

  • splitwise_get_current_user
  • splitwise_update_user

Group Tools

  • splitwise_get_groups
  • splitwise_get_group
  • splitwise_create_group
  • splitwise_delete_group
  • splitwise_undelete_group
  • splitwise_add_user_to_group
  • splitwise_remove_user_from_group

Friend Tools

  • splitwise_get_friends
  • splitwise_get_friend

Expense Tools

  • splitwise_get_expense
  • splitwise_get_expenses
  • splitwise_create_expense
  • splitwise_update_expense
  • splitwise_delete_expense
  • splitwise_undelete_expense

Notification Tools

  • splitwise_get_notifications
  • splitwise_check_auth

Each tool includes input validation via zod (see src/index.ts for parameter shapes).

MCP Inspector — Testing & Development 🧩

The easiest way to test and interact with your deployed MCP server is using the official MCP Inspector tool. This provides a web-based interface to explore and test all available MCP tools.

Quick Start with MCP Inspector

  1. Ensure your server is deployed and accessible

    pnpm deploy
# Note your deployed URL: https://your-deployed-url.workers.dev

  2. Launch MCP Inspector

    # Using pnpx (recommended)
pnpx @modelcontextprotocol/inspector@latest

# Or using npx
npx @modelcontextprotocol/inspector@latest

# Or using bunx
bunx @modelcontextprotocol/inspector@latest

  3. Connect to your MCP server

    • The inspector will open in your browser
    • Enter your server URL: https://your-deployed-url.workers.dev/sse
    • The inspector will automatically discover all available tools

  4. Test OAuth flow

    • First visit https://your-deployed-url.workers.dev/authorize to complete Splitwise OAuth
    • Then return to the inspector to test authenticated tools

Available Tools in Inspector

Once connected, you'll see all available tools including:

Server Info

  • about — Get server information and version
  • validate — Test server connectivity

User Management

  • splitwise_get_current_user — Get authenticated user details
  • splitwise_update_user — Update user information

Group Management

  • splitwise_get_groups — List all groups
  • splitwise_create_group — Create new group
  • splitwise_add_user_to_group — Add members to group

Expense Tracking

  • splitwise_create_expense — Create new expense
  • splitwise_get_expenses — List expenses with filters
  • splitwise_update_expense — Modify existing expense

Authentication

  • splitwise_check_auth — Verify authentication status

Inspector Benefits

✅ Visual interface — No need to craft JSON requests manually
✅ Schema validation — Built-in parameter validation and hints
✅ Real-time testing — Immediate feedback on tool responses
✅ Tool discovery — Automatically lists all available tools
✅ Error debugging — Clear error messages and stack traces

Example Workflow

  1. Start inspector: pnpx @modelcontextprotocol/inspector@latest
  2. Connect to: https://your-deployed-url.workers.dev/sse
  3. Test connection with about tool
  4. Complete OAuth at /authorize endpoint
  5. Test authenticated tools like splitwise_get_current_user
  6. Create expenses, manage groups, etc.

For Production Integrations

After testing with the inspector, use your deployed server with:

Claude Desktop

{
	"mcpServers": {
		"splitwise": {
			"command": "node",
			"args": [
				"path/to/mcp-client.js",
				"https://your-deployed-url.workers.dev/sse"
			]
		}
	}
}

Cursor or other MCP clients

  • Configure MCP server URL: https://your-deployed-url.workers.dev/sse
  • The client will automatically discover and use available tools

Custom Applications

import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const client = new Client({
	name: "your-app",
	version: "1.0.0",
});

// Connect to your deployed server
await client.connect("https://your-deployed-url.workers.dev/sse");

💡 Pro tip: Always test your tools with the MCP Inspector first before integrating with other clients. It's the fastest way to debug issues and understand tool behavior.

Usage Examples 📝

Creating an Expense

{
	"tool": "splitwise_create_expense",
	"input": {
		"cost": "20.00",
		"description": "Dinner at restaurant",
		"users": [
			{ "user_id": 123, "paid_share": "10.00", "owed_share": "10.00" },
			{ "user_id": 456, "paid_share": "10.00", "owed_share": "10.00" }
		]
	}
}

Getting Current User Info

{
	"tool": "splitwise_get_current_user",
	"input": {}
}

Creating a Group

{
	"tool": "splitwise_create_group",
	"input": {
		"name": "Weekend Trip",
		"type": "trip"
	}
}

Getting Expenses with Filters

{
	"tool": "splitwise_get_expenses",
	"input": {
		"group_id": 123,
		"limit": 10,
		"dated_after": "2024-01-01"
	}
}

Security 🔒

  • All Splitwise API calls use OAuth 2.0
  • Secrets are stored as Wrangler/Cloudflare environment variables
  • Redis connections use authenticated tokens
  • No sensitive data is logged in production

Troubleshooting 🔧

OAuth Redirect Issues

  • Ensure SPLITWISE_CALLBACK_URL matches exactly what's configured in your Splitwise app
  • Verify the callback URL is publicly accessible

Redis Connection Errors

  • Verify REDIS_URL and REDIS_TOKEN are correct
  • Check Redis instance is accessible from Cloudflare Workers

MCP Tool Authentication

  • Most tools require a valid authenticated user session
  • Use the splitwise_check_auth tool to verify authentication status
  • Complete OAuth flow at /authorize endpoint if not authenticated

Rate Limits

  • The server respects Splitwise API rate limits
  • If you encounter rate limiting, the server will return appropriate error messages
  • Consider implementing client-side retry logic with exponential backoff

Interactive Examples 🧪

  1. Start local dev server and open the authorize URL in a browser to run the OAuth flow:

    pnpm dev
# then open http://127.0.0.1:8787/authorize (or the URL shown by Wrangler)

  2. Use the about tool via your MCP client to check the server is alive (MCP client or agent required). The server will respond with a JSON about payload. If you need to test tools manually, consult the MCP client you use (this repo provides the server side). Tools require a valid authenticated user prop for many actions.

Deployed MCP Server — Preferred for Integrations ✅

You have deployed the MCP server — great. Use the deployed instance as the primary integration target for hosted LLM platforms (Claude, Cursor), external agents, and any production workflows.

Deployed Server Advantages

  • Public, stable URL that works with OAuth redirects and platform integrations
  • Durable Object and Redis behave like production (no local environment gaps)
  • Easier to share with teammates or third-party LLM platforms without exposing your machine

Typical deployed URL: https://<your-deployed-subdomain>.workers.dev (or your custom domain). The MCP API is mounted at /sse. OAuth endpoints remain at /authorize, /token, and /register.

Quick Check (Deployed About Tool)

curl -X POST "https://your-deployed-url.workers.dev/sse" \
  -H "Content-Type: application/json" \
  -d '{"tool":"about","input":{}}'

If you integrate with hosted LLM platforms, point their tool/plugin/interceptor configuration to the deployed /sse endpoint or use a small proxy adapter to adapt request envelopes. If that returns an error, consult your MCP client for the exact request envelope. The goal is to reach the deployed /sse endpoint with the tool invocation that your client expects.

Contributing 🤝

Contributions are welcome. Please follow these small guidelines:

  • Fork the repo and open a PR
  • Run formatting and linting before committing: pnpm format and pnpm lint:fix
  • Make sure TypeScript type checks pass: pnpm type-check

Suggested Low-Risk Improvements

  • Add unit tests for the SplitwiseAuthService wrappers
  • Add CI to run pnpm type-check, pnpm format --check and pnpm lint