beaver-mcp

Personal remote MCP server on Cloudflare Workers, connected to Claude as a custom connector at https://mcp.alanko.dev/mcp.

Tools

Tool	What it does
lunchmoney_list_transactions	List/filter transactions (date range, category, tag, status, pending)
lunchmoney_get_transaction	Single transaction with split/group children
lunchmoney_update_transaction	Update payee, category, notes, status, tags, amount
lunchmoney_create_transaction	Create a manual transaction
lunchmoney_list_categories / _tags / _accounts	ID lookups for updates

Auth: the endpoint is public, so /mcp sits behind OAuth (@cloudflare/workers-oauth-provider). Claude signs in via GitHub; only logins in the ALLOWED_GITHUB_LOGINS secret may authorize (empty = deny all).

The server is structured so any API becomes MCP tools with one folder (client.ts + tools.ts) and one line in src/index.ts — see the recipe in CLAUDE.md.

Setup

1. GitHub OAuth Apps (one-time)

GitHub → Settings → Developer settings → OAuth Apps → New OAuth App. Create two:

	Homepage	Callback
dev	http://localhost:8788	http://localhost:8788/callback
prod	https://mcp.alanko.dev	https://mcp.alanko.dev/callback

No scopes needed (only the public profile is read).

2. Lunch Money

Create a personal access token at my.lunchmoney.app/developers.

3. Local dev

pnpm install
cp .dev.vars.example .dev.vars   # fill in dev OAuth app + token; COOKIE_ENCRYPTION_KEY = openssl rand -hex 32
pnpm dev                          # http://localhost:8788/mcp
pnpm test

4. Deploy

npx wrangler kv namespace create OAUTH_KV   # put the returned id into wrangler.jsonc
pnpm deploy

# production secrets:
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY
npx wrangler secret put ALLOWED_GITHUB_LOGINS   # your GitHub username
npx wrangler secret put LUNCHMONEY_TOKEN

CI (.github/workflows/ci.yml) typechecks/lints/tests every PR and push to main, and deploys on main after checks pass. Repo secrets required: CLOUDFLARE_API_TOKEN (Edit Workers template), CLOUDFLARE_ACCOUNT_ID.

5. Connect to Claude

claude.ai → Settings → Connectors → Add custom connector → https://mcp.alanko.dev/mcp → sign in with GitHub.