A portable Docker-based server that exposes Monarch Money personal finance data via two protocols simultaneously:
/mcp — FastMCP streamable-HTTP for AI assistants that support the MCP protocol. With OAuth enabled it works as a custom connector in Claude Desktop, claude.ai, and the mobile apps.
FastMCP Python MCP server + REST API for Monarch Money — Docker-based, stateless, dual-protocol (any MCP client + any REST client)
/api/* — Plain REST endpoints for automation tools like n8n, Zapier, or custom scripts
The server uses the token directly and never makes a login call — this is stateless and works perfectly across container restarts.
Where to find your token in a browser: Open Monarch Money → DevTools (F12) → Application tab → Local Storage → look for a key containing token. Or: Network tab → any API request → copy the Authorization: Token ... header value.
Step 4 — Start the server
docker compose up -d
Step 5 — Verify it's working
# Health check (no auth needed)
curl http://localhost:8000/health
# Fetch your accounts (replace with your MCP_API_KEY)
curl -H "Authorization: Bearer your-generated-key-here" http://localhost:8000/api/accounts
You should see {"status": "ok"} and a JSON list of your accounts. If you do, you're good to go.
Next: connect it to Claude. Claude Connector Setup is the path most people want — it covers Claude Desktop, claude.ai, and mobile in one setup. If you only ever use this from Claude Desktop against a local server, the local stdio bridge is simpler.
Claude Connector Setup (OAuth)
This is how you get the tools into Claude Desktop, claude.ai, and the mobile apps — one setup, all three surfaces.
Claude's "Add custom connector" dialog does not accept a static Authorization: Bearer header (the request for it was closed as not planned), so reaching those surfaces requires OAuth. This server ships an optional GitHub-backed OAuth flow that admits exactly one GitHub account: yours.
Prerequisite: the server must be reachable over public HTTPS. Anthropic's infrastructure — not your laptop — makes the outbound call, so localhost cannot work here. See Coolify Deployment for one way to get there, or use any host that terminates TLS for you. For local-only use, skip to Local stdio bridge below.
The callback URL must match exactly — it is PUBLIC_BASE_URL + /auth/callback, and GitHub permits only one. Generate a client secret and keep it with the client ID.
PUBLIC_BASE_URL must not include /mcp. Claude is given ${PUBLIC_BASE_URL}/mcp, but this variable is the base. Include /mcp here and the entire OAuth surface relocates under /mcp/..., discovery 404s, and the connector fails with an unhelpful client-side error.
FASTMCP_HOME=/data points OAuth state at the named volume declared in docker-compose.yml. Without a persistent volume there, every redeploy wipes the registered client and forces you to re-authorize the connector by hand.
Step 3 — Deploy and verify
Deploy with those variables set (Coolify Deployment covers one setup), then:
Expect 19/19. The EXPECT_OAUTH=1 flag matters: without it, a dead OAuth surface is reported as a skip and the run still exits 0, so a broken deploy looks green. With it, the three OAuth checks fail loudly.
Three of those assertions are the ones worth reading if something goes wrong:
resource in the protected-resource metadata must equal the URL you type into Claude, character for character.
Unauthenticated POST /mcp must return 401with a WWW-Authenticate header — that header is what makes Claude show a Connect button instead of an error.
The authorization-server metadata must advertise S256 PKCE and a registration_endpoint, because Claude requires Dynamic Client Registration.
Step 4 — Add the connector
In Claude Desktop → Settings → Connectors (on claude.ai it's Customize → Connectors):
+ → Add custom connector
URL: https://your-host.example.com/mcp — with/mcp this time
Leave Advanced settings empty. Those OAuth Client ID/Secret fields are for servers that don't support Dynamic Client Registration; this one does, so Claude registers itself.
Approve the consent screen, then sign in with GitHub
Per conversation, enable it with the + button → Connectors.
Mobile needs no setup. The connector lives on your Anthropic account, so it appears on iOS and Android at your next login. (Adding connectors from mobile is in beta; Desktop and web are the supported path.)
Notes
Only GITHUB_ALLOWED_USER gets in. Any other GitHub account can complete the sign-in, then receives 401 on every tool call. Fail-closed on data.
MCP_API_KEY still works on /mcp. OAuth adds a door without locking the old one, which keeps n8n and existing Claude Code configs working unchanged. It also means a leaked MCP_API_KEY still reaches every tool — treat it accordingly.
Keep the --header entry in your Claude Code config. Account-level connectors are known-broken in Claude Code mode (claude-code#57158, closed as not planned): they return 403 while working normally in Claude chat. The static-key path bypasses Anthropic's connector proxy entirely and is the reliable fallback.
/register is unauthenticated by protocol and its client registrations are written without a TTL. If your server is publicly discoverable, consider a reverse-proxy rate limit on that path that excludes Anthropic's egress range 160.79.104.0/21.
Local stdio bridge (Claude Desktop only)
For a server running on localhost, or if you'd rather not set up OAuth. This path works only in Claude Desktop — it cannot reach claude.ai or mobile.
Add this to your claude_desktop_config.json. Since that file accepts only stdio-based MCP entries, use mcp-proxy as a bridge:
Where OAuth state persists (/data, mounted volume)
You need eitherMONARCH_TOKENor both MONARCH_EMAIL + MONARCH_PASSWORD. Token is preferred — it's faster and stateless.
GITHUB_CLIENT_ID is an on/off switch for OAuth. Leave it empty and the server behaves exactly as it did before OAuth existed. Set it and the other three become mandatory — the server refuses to boot without them rather than starting up half-configured.
When a session expires
Monarch tokens go stale eventually. When a call comes back 401, the server re-authenticates once with MONARCH_EMAIL / MONARCH_PASSWORD (+ auto-TOTP) and retries that call. Concurrent 401s share a single login, so a rotating TOTP code is never spent twice.
Set all three — MONARCH_TOKENand the credentials — for the best of both: fast stateless startup, plus self-healing when the token dies. With a token but no credentials there is nothing to re-mint, so the 401 surfaces and you have to replace MONARCH_TOKEN by hand.
A second consecutive 401 is treated as a real auth failure (wrong password, revoked MFA) and surfaces rather than retrying.
If the re-login itself is rejected, the server backs off for 60s (AUTH_COOLDOWN_SECONDS) before attempting another one. Requests during the cooldown fail fast with the underlying 401 instead of each firing its own login — a stuck credential should not turn every incoming request into a login attempt against Monarch.
Reading the error tells you which layer broke: HTTP Code 401: Unauthorized means the login was rejected, while 401, message='Unauthorized', url='...graphql' means the session expired and the retry is about to run.
2FA / TOTP Setup
If your Monarch account has two-factor authentication enabled, you must provide the raw Base32 secret key — NOT the 6-digit rotating code you type when logging in.
Finding your TOTP secret
From a password manager (e.g. 1Password, Bitwarden):
Open your Monarch Money login entry
Click Edit
Find the OTP / Authenticator field → Copy Secret Key
It looks like: JBSWY3DPEHPK3PXP (uppercase letters and numbers, ~20–32 characters)
From Monarch directly (requires disabling and re-enabling 2FA):
Go to Settings → Security → Two-factor authentication
Click Disable, then re-enable it
On the setup screen, Monarch shows a "two-factor text code" — that's the raw seed
Add it to .env:
MONARCH_MFA_SECRET=JBSWY3DPEHPK3PXP
The server uses the monarchmoney library to auto-compute the 6-digit TOTP code from the secret — you never need to type the 6-digit code manually.
Important:MONARCH_MFA_SECRET is only needed when using email/password login (Option A). If you're using MONARCH_TOKEN directly, 2FA is already baked into the token and this variable is not needed.
REST API Endpoints
All endpoints require: Authorization: Bearer {MCP_API_KEY} except /health.
GET /health
Unauthenticated health check.
{ "status": "ok" }
GET /api/accounts
All accounts with current balances, types, and metadata.
No query parameters.
GET /api/transactions
Transactions with optional filtering.
Parameter
Type
Default
Description
limit
integer
100
Max transactions to return (max 500)
start_date
YYYY-MM-DD
—
Filter from this date inclusive
end_date
YYYY-MM-DD
—
Filter to this date inclusive
search
string
—
Free-text search across merchant/description
category_ids
string (comma-separated IDs)
—
Restrict to these category IDs
account_ids
string (comma-separated IDs)
—
Restrict to these account IDs
tag_ids
string (comma-separated IDs)
—
Restrict to these tag IDs
has_attachments
boolean
—
Filter by attachment presence
has_notes
boolean
—
Filter by note presence
is_split
boolean
—
Filter split transactions
is_recurring
boolean
—
Filter recurring transactions
Example:
GET /api/transactions?limit=50&start_date=2026-03-01&end_date=2026-03-31&search=Netflix
GET /api/cashflow
Detailed cashflow breakdown by category for a period.
Parameter
Type
Description
start_date
YYYY-MM-DD
Period start
end_date
YYYY-MM-DD
Period end
GET /api/budgets
Budget categories with planned amounts and actual spending.
Parameter
Type
Description
start_date
YYYY-MM-DD
Budget period start
end_date
YYYY-MM-DD
Budget period end
GET /api/recurring
Recurring transactions and subscriptions.
Parameter
Type
Description
start_date
YYYY-MM-DD
Period start
end_date
YYYY-MM-DD
Period end
GET /api/networth
Historical net worth snapshots (wraps get_aggregate_snapshots).
This server is Coolify-ready. The docker-compose.yml uses an environment: block with ${VAR} substitution — Coolify detects these and surfaces them in its Environment Variables UI. No .env file needed on the server.
Create a new Coolify resource → Docker Compose
Point it at this repository
Set your environment variables in the Coolify UI (MCP_API_KEY is required; others are optional with sensible defaults)
If you're enabling the Claude connector, two extra things matter here:
The compose file declares a named volume oauth-state mounted at /data. Coolify persists named volumes across deploys, which is what keeps the connector authorized through a rebuild.
Anthropic reaches your server from 160.79.104.0/21 with a 10-second budget on OAuth discovery, registration, and token calls. A WAF, rate limit, or geo-block in front of Traefik can break the connector while /health still looks perfectly fine.
Acknowledgments
This project is built on top of monarchmoney by @hammem — the Python client library that handles all Monarch Money API communication. None of this would be possible without that work.
M
Monarch Money
richardadonnell·4 ดาว·
FastMCP Python MCP server + REST API for Monarch Money — Docker-based, stateless, dual-protocol (any MCP client + any REST client)