Spliit MCP for Cloudflare Workers

An unofficial, security-focused MCP server for Spliit. One remote MCP connection can remember many groups, keep one active group, and read or deliberately create Spliit data. It is designed for a personal Cloudflare Worker deployment.

A normal Spliit group link is sufficient. No modified Spliit backend or Spliit account is required.

Version 1 breaking change

Version 1 replaces per-call group arguments with a durable active-group model:

• list_groups lists remembered aliases and the active alias;

• select_group changes the active group for later reads and preparations;

• read tools no longer accept a group argument;

• direct create tools are replaced by prepare_expense, prepare_reimbursement, and commit_draft;

• group credentials and drafts are encrypted inside a SQLite Durable Object;

• the old SPLIIT_GROUPS_JSON secret is imported once for a safe upgrade.

Prepared drafts contain an immutable encrypted copy of their target. Selecting another group before commit_draft cannot redirect the write.

Related MCP server: SplitwiseMCP

Version 1.1 group management

• add_group_from_link accepts a normal group link, verifies it, encrypts it in the Cloudflare registry, derives a unique alias when needed, and selects it;

• create_group creates a group on the active group's Spliit server, or on public spliit.app when the registry is empty, then remembers and selects it;

• neither tool returns the secret group URL or ID;

• create_group is registered only when WRITES_ENABLED is "true".

Install with an AI coding agent (recommended)

Give a trusted coding agent terminal and browser access, then paste:

Install Spliit MCP from https://github.com/kegelmeier/spliit-mcp-cloudflare
into my Cloudflare account. Read AGENTS.md and docs/agentic-install.md completely
before acting. Keep the default prepare/commit write workflow enabled, but do
not invoke it during installation. Never ask me to paste a Spliit group URL
into chat, a command argument, source control, or logs. Use Wrangler's
interactive Cloudflare login. Generate separate 32-byte MCP and admin tokens
and a 32-byte data-encryption key without displaying them. Deploy with an empty
SPLIIT_GROUPS_JSON bootstrap value, validate /healthz and authentication, then
give me the /setup URL so I can add group links privately in my browser.
Configure one Streamable HTTP MCP connection with an environment-backed bearer
token. Confirm the four write tools are present without invoking them.

Existing 0.x deployments need the upgrade variant in Agentic installation.

Other installation paths

• Terminal installation

• Cloudflare and MCP client UI

• MCP client setup

• Troubleshooting

Tools

Write tools are registered by default. Set WRITES_ENABLED to "false" and redeploy only when an intentionally read-only Worker is required; link import remains available because it changes only the encrypted registry. Tool availability is not permission to mutate: clients should require approval for create_group, and always inspect a prepared expense preview and obtain separate approval before commit_draft. There are no update or delete tools.

Configuration

Four encrypted Worker secrets are required:

Do not change DATA_ENCRYPTION_KEY after groups are stored. There is no automatic key-rotation migration in version 1.

Non-secret variables live in wrangler.jsonc:

Self-hosted Spliit installations must be explicitly added to ALLOWED_SPLIIT_HOSTNAMES before their links can be stored.

Security and persistence

• /mcp and /admin use separate bearer tokens.

• The MCP client receives aliases, never stored group URLs or IDs. If add_group_from_link is invoked, the supplied link necessarily passes through that one authenticated MCP request but is not returned.

• Group records, draft payloads, and completed draft results are encrypted with AES-256-GCM and record-specific associated data before SQLite persistence.

• The setup page is same-origin, non-cacheable, frame-protected, and stores the admin token only in the current page's memory.

• One-time draft claims prevent concurrent duplicate commits. A completed draft is replay-safe. An interrupted ambiguous commit remains locked so the user can verify Spliit instead of risking an automatic duplicate.

• MCP transport requests remain stateless; only application state is durable.

• Request tracing is intentionally disabled because Spliit tRPC URLs can contain group IDs.

Read SECURITY.md before deployment.

Limits and cost

There is no application-level group-count cap. Practical capacity and cost are bounded by Cloudflare Durable Objects storage/request limits and the Spliit server. Expense/activity pages remain limited to 50 records and upstream responses to 2 MiB.

The design is intended to fit ordinary personal use on Cloudflare's Free plan, but platform limits can change. Check current Durable Objects pricing, Workers pricing, and platform limits.

Compatibility and non-goals

• Spliit has no account API for discovering every group; each existing link is added once through setup or add_group_from_link.

• The Worker calls Spliit's unofficial tRPC procedures. Upstream changes can require an update.

• Attachments, recurring creation, custom splits, updates, and deletion are not implemented.

• This project is not affiliated with Spliit or Cloudflare.

Development

npm ci
cp .dev.vars.example .dev.vars
npm run dev
npm run check

Use placeholders only in tracked files and tests. See CONTRIBUTING.md and Architecture.

License

MIT