wallos-mcp

Your self-hosted Wallos subscription tracker, served to any MCP client, from your own Cloudflare Worker.

OAuth 2.1 + PKCE Wallos 5.0+ several instances MIT

MCP clientClaude Code · claude.ai · mobile

→

your WorkerOAuth server + agent

→

your Wallosone account per grant

Each connection signs in separately, by naming a Wallos instance and pasting that instance's API key. The key is held in the encrypted grant inside this deployment's Cloudflare KV namespace, and is never sent to the MCP client. Connecting twice binds two accounts — a personal instance and a household one, for example.

0 Connect to this deployment

Already running Wallos 5.0 or newer, reachable over HTTPS? Point a client here and sign in.

claude mcp add --transport http wallos https://wallos-mcp.mkpo.li/mcp

In claude.ai it is Settings → Connectors → Add custom connector with https://wallos-mcp.mkpo.li/mcp. Leave any client ID and secret fields empty.

Your API key is stored, encrypted, by whoever operates this deployment, and it carries the same authority over your subscriptions as your Wallos password. Regenerating the key in Wallos ends that access immediately. The rest of this page is for running your own copy instead, which takes about five minutes and keeps the key on your own account.

1 Get your Wallos API key

In Wallos, open Settings and find the API key field on your own profile. Generate one if the field is empty, and copy it.

The key carries the same authority over your data as your password does: everything this server can read or change, it changes as you. Wallos lets you regenerate it at any time, which immediately invalidates the old one and any connection holding it.

2 Deploy the Worker

You need a Cloudflare account and bun. Without a custom domain the Worker answers on workers.dev.

git clone https://github.com/mkpoli/wallos-mcp && cd wallos-mcp
bun install
bun run setup

bun run setup asks which domain to answer on, creates the KV namespace, takes ALLOWED_HOSTS, generates a cookie key, and deploys. Re-running it to rotate one secret is safe.

3 Decide which instances may be reached

ALLOWED_HOSTS is the list of Wallos hosts a connection is allowed to name. The MCP endpoint is public and clients register themselves, so this is what stops a stranger from pointing your deployment at somebody else's instance.

Value	Meaning
`wallos.example.com`	that one instance
`wallos.example.com, money.example.org`	either of them
`*.example.com`	any host in the domain
`*`	any host at all, making the deployment a relay anyone may bind to their own tracker
empty	nobody signs in

4 Connect a client

Leave any client ID and secret fields empty — MCP clients register themselves.

claude mcp add --transport http wallos https://<your-host>/mcp

Run /mcp in Claude Code to sign the connection in. In claude.ai it is Settings → Connectors → Add custom connector with the same URL. Any single-segment label after /mcp/ — /mcp/household, say — is a separate connection with its own grant, which is how one deployment serves several trackers to clients that reject two servers sharing a URL.

5 What you get

✓Subscriptions — list with filters, read one, create, edit, delete, monthly cost, iCal feed

✓Master data — categories, payment methods, household members and currencies, each readable and writable

✓Names instead of ids — "Netflix, ¥1490 monthly, Entertainment, paid by card" creates the category and the payment method if your instance lacks them

✓Settings — display preferences, notification settings, exchange-rate provider

Administration tools — OIDC, registration, SMTP, disabling password login — are registered only when the deployment sets ADMIN_TOOLS to 1. They rewrite how everyone signs in to the instance, and a mistaken call can lock you out of your own tracker.