Splitwise connector for ChatGPT

A data-only MCP server that connects ChatGPT to Splitwise's official API. It supports:

• list_groups (compact, paginated groups and members)
• list_friends (compact, paginated balances)
• list_expenses (compact, paginated summaries)
• get_expense
• create_expense (equal group split or explicit shares)
• update_expense (complete replacement shares for an existing expense)

The server uses Streamable HTTP at /mcp. It also acts as a small OAuth 2.1 authorization bridge: ChatGPT completes PKCE with this server, while this server completes Splitwise OAuth and keeps the Splitwise token out of ChatGPT.

Prerequisites

• Node.js 20 or newer
• A stable public HTTPS URL for deployment (or a development tunnel while testing)
• A Splitwise account and Splitwise OAuth application

1. Register the Splitwise application

1. Open https://secure.splitwise.com/apps and create an OAuth application.
2. Set its callback URL to https://YOUR-CONNECTOR-HOST/oauth/splitwise/callback.
3. Copy the client ID and client secret. Never commit them.

Splitwise must redirect to the connector, not directly to ChatGPT. The connector resumes ChatGPT's separate PKCE flow afterward.

2. Configure and run

cp .env.example .env
# Fill in .env, then:
npm install
npm run dev

Required variables:

Variable	Purpose
PUBLIC_BASE_URL	Public HTTPS origin, without a trailing slash
SPLITWISE_CLIENT_ID	Splitwise OAuth app client ID
SPLITWISE_CLIENT_SECRET	Splitwise OAuth app secret
SESSION_SECRET	Stable random secret, at least 32 characters, used to authenticate and encrypt OAuth artifacts

Optional variables: PORT, SPLITWISE_AUTHORIZE_URL, SPLITWISE_TOKEN_URL, and SPLITWISE_API_BASE_URL.

Generate a session secret with openssl rand -hex 32. For a container:

docker build -t splitwise-mcp .
docker run --env-file .env -p 3000:3000 splitwise-mcp

3. OAuth flow

1. ChatGPT discovers /.well-known/oauth-protected-resource from the MCP server.
2. It discovers this connector's OAuth metadata at /.well-known/oauth-authorization-server and dynamically registers a public client at /register.
3. ChatGPT starts authorization-code + PKCE at /authorize, including the MCP resource value.
4. The connector redirects the user to Splitwise and receives the result at /oauth/splitwise/callback.
5. The connector exchanges Splitwise's code server-side, creates a five-minute encrypted connector code, and redirects to ChatGPT.
6. ChatGPT exchanges that code at /token using its PKCE verifier. The connector returns an authenticated, encrypted access token containing the minimum session context.
7. Every /mcp request decrypts and validates the token, expiry, scope context, and resource before calling Splitwise.

Dynamic client registrations, connector codes, and 30-day access tokens are stateless AES-256-GCM envelopes derived from SESSION_SECRET. They survive sleeping, restarts, redeploys, and multiple replicas as long as every instance keeps the same secret. Rotating SESSION_SECRET intentionally invalidates every existing registration and connection. This sample does not issue refresh tokens, so relinking is required after 30 days.

4. Test and connect to ChatGPT

Run:

npm run build
npm test
npx @modelcontextprotocol/inspector@latest

In the Inspector choose Streamable HTTP and use https://YOUR-CONNECTOR-HOST/mcp.

In ChatGPT, enable Developer mode under Settings → Security and login. In the Plugins page, add a connection, choose the public endpoint option, and enter https://YOUR-CONNECTOR-HOST/mcp. Review the five discovered tools, then invoke a read tool to start account linking.

Suggested checks:

• “List my Splitwise groups.”
• “Show balances with my Splitwise friends.”
• “List the latest five expenses in group 123.”
• “Get full details for expense 456.”
• “Create a $24 USD dinner expense in group 123, split equally.”

Production notes

The runnable server stores no OAuth session state. Before a larger multi-user deployment:

• Keep SESSION_SECRET stable, secret, and identical across replicas. For stronger key management, derive or retrieve the encryption key from a managed KMS; never log tokens or secrets.
• Stateless authorization codes cannot be marked consumed without storage. PKCE, exact client/redirect/resource binding, authenticated encryption, and the five-minute lifetime limit replay exposure. If strict single-use enforcement is required, add a short-lived shared replay cache keyed by a code identifier.
• Restrict dynamic-registration redirect URIs to the exact ChatGPT callback URLs shown by the app management page (plus explicitly configured development callbacks).
• Add rate limiting, structured security logs, secret rotation, a privacy policy, and token revocation/account unlinking.
• The service emits privacy-safe structured request and tool telemetry (request ID, tool name, duration, status) without OAuth tokens, arguments, or Splitwise response data.
• Preserve the resource binding, PKCE verification, short code lifetime, and exact redirect-URI matching.
• Run behind HTTPS. Do not expose this development server directly to the internet.

The create_expense tool is marked as a non-idempotent write. Its instructions tell the model to summarize the exact amount, currency, group, payer, and shares before calling it. Splitwise can return HTTP 200 with an application-level errors object, so the connector checks that object before reporting success.