monzo-mcp
MCP server for the Monzo banking API. Read-only access to accounts, balances, pots, transactions, and spending analysis - all through Claude Code or any MCP client.
Unlike other Monzo MCP implementations that use raw bearer tokens (which expire in 6 hours), this server handles full OAuth with automatic token refresh.
Features
- 7 read-only tools - no write operations, no money movement
- OAuth with auto-refresh - tokens refresh automatically, no manual regeneration
- Local transaction cache - SQLite database survives Monzo's 90-day SCA window
- Auto-sync on demand - the cache-reading tools run an incremental sync automatically if the cache wasn't synced today, so you rarely need to call
monzo_syncby hand - Spending analysis - category breakdowns, top merchants, month-over-month comparison
- Transaction search - search by merchant, payee (counterparty), description, or notes across cached history
- Counterparty details - bank transfers (faster payments, p2p, Bacs) are cached with the payee's name, sort code, and account number
Tools
| Tool | Description | Data source |
|---|---|---|
monzo_list_accounts | List accounts with types and IDs | Live API |
monzo_get_balance | Current balance and spend today | Live API |
monzo_list_pots | Savings pots and balances | Live API |
monzo_sync | Sync transactions to local cache | Live API -> SQLite |
monzo_list_transactions | List/filter cached transactions | Local cache (auto-syncs if stale) |
monzo_search_transactions | Search by merchant/payee/description/notes | Local cache (auto-syncs if stale) |
monzo_spending | Spending analysis with category breakdown | Local cache (auto-syncs if stale) |
Prerequisites
- Python 3.13+
- uv (recommended) or pip
- A Monzo account with an OAuth client registered at developers.monzo.com
Installation
git clone https://github.com/partymola/monzo-mcp.git
cd monzo-mcp
uv venv --python 3.13 .venv
uv pip install -e .
Setup
1. Register a Monzo OAuth client
Go to developers.monzo.com and create an OAuth client:
- Set the redirect URL to
http://localhost:6600/callback - Note your Client ID and Client Secret
2. Authenticate
monzo-mcp auth
This opens your browser for Monzo OAuth. After authorizing, approve the login in your Monzo app within 5 minutes for full transaction history access (Monzo's SCA window).
3. Register with Claude Code
claude mcp add -s user monzo -- /path/to/monzo-mcp/.venv/bin/monzo-mcp
4. First sync
In Claude Code, run monzo_sync to populate the local transaction cache. Do this immediately after auth to take advantage of the SCA window (up to 11 months of history).
CLI
monzo-mcp Start the MCP server (stdio transport)
monzo-mcp auth Interactive OAuth setup (opens the browser)
monzo-mcp --version Print the installed package version
Configuration
All configuration is via environment variables (optional):
| Variable | Default | Description |
|---|---|---|
MONZO_MCP_CONFIG_DIR | <package>/config/ | Directory for OAuth credentials and tokens |
MONZO_MCP_DB_PATH | <package>/monzo.db | Path to SQLite transaction cache |
Credential files (created by monzo-mcp auth):
config/monzo_client.json- OAuth client ID and secretconfig/monzo_tokens.json- Access and refresh tokens (auto-refreshed)
Monzo SCA window
Monzo's Strong Customer Authentication (SCA) limits transaction history access:
- Within 5 minutes of app approval: up to ~11 months of history
- After the window expires: only the last 90 days
The local SQLite cache preserves all synced transactions permanently, so run monzo_sync promptly after monzo-mcp auth.
To backfill a specific range, pass since to monzo_sync - an ISO date (2026-01-01) or datetime (2026-01-01T14:30:00Z). Reaching back more than ~90 days only works inside the SCA window; outside it, only the last 90 days are returned.
Older cached transactions gain fields added in newer versions (e.g. counterparty/payee details on bank transfers) only when re-fetched, which a post-auth full sync does for the history it re-pulls.
Security
- Zero write tools - cannot send money, move funds between pots, or modify transactions
- Monzo API itself cannot send money to external accounts
- Tokens stored as JSON files in the
config/directory (gitignored) - All API calls are GET requests with Bearer token auth
Troubleshooting
- "SCA required" or only 90 days of history - re-run
monzo-mcp authand approve the login in the Monzo app within 5 minutes, then sync straight away (see the SCA window above). - Token expired / no refresh - re-run
monzo-mcp authto re-authorise. - "No transaction data available" - the cache is empty; call
monzo_sync(or any cache-reading tool, which auto-syncs) once after authenticating.
Contributing
See CONTRIBUTING.md for development setup, the test workflow, and the pre-commit hook. Changes are tracked in CHANGELOG.md.
License
GPL-3.0-or-later. See LICENSE.