Monzo MCP

A local Python 3.12 MCP server for using the Monzo developer API from Codex, Claude Desktop, and Claude Code. It runs over stdio on your machine; it does not expose a listening MCP port or send your Monzo client secret to an MCP host.

The implementation follows the Monzo API reference, the official MCP Python SDK, and the current local-server configuration documented by MCP.

What it supports

Area	MCP tools
Authentication	get_authentication_status, who_am_i, refresh_authentication, logout
Accounts and balances	list_accounts, get_balance
Pots	list_pots, deposit_into_pot, withdraw_from_pot
Transactions	get_transaction, list_transactions, annotate_transaction
Reconciliation	list_transactions_across_accounts, get_reconciliation_snapshot
Feed	create_feed_item
Attachments	request_attachment_upload, upload_attachment_from_path, register_attachment, deregister_attachment
Receipts	create_or_update_receipt, get_receipt, delete_receipt
Webhooks	register_webhook, list_webhooks, delete_webhook

get_reconciliation_snapshot is the main tool for bill checking. It returns personal and joint account balances, all associated pot balances, currency totals, and a newest-first merged transaction list. The default range is the previous 30 days; pass since and before as RFC3339 timestamps for another range.

Monzo API constraints

• The developer API is for your own account or a small explicitly allowed set of users, not a public application.
• Access has no permissions until you approve the Strong Customer Authentication notification in the Monzo app.
• For five minutes after authentication Monzo permits full transaction history; afterwards a client can only sync the previous 90 days. This server does not maintain a historical database.
• Transactions belong to personal or joint current accounts. Monzo exposes pot balances and deposit/withdraw operations, but no separate pot transaction-list endpoint.
• All monetary amounts are integer minor units. For GBP, 1250 means £12.50.
• Monzo limits transaction pages to 100. The reconciliation helpers follow cursors automatically up to max_transactions_per_account (default 500, maximum 5,000).
• Pots with added security cannot be withdrawn through the API.

Security choices

• Use a confidential Monzo OAuth client so Monzo issues a refresh token.
• The client ID and secret come from environment variables or private files. They are never MCP tool arguments or tool output.
• OAuth tokens default to ~/.local/share/monzo-mcp/tokens.json, written atomically with mode 0600 inside a 0700 directory.
• A file lock coordinates refresh-token rotation when Codex and Claude run the server at the same time. Monzo refresh tokens are one-use and the old access token is invalidated on refresh.
• Every operation that changes Monzo data, moves money, uploads a local file, or logs out requires an explicit confirm=true. MCP read/write/destructive annotations are also advertised.
• The stdio server writes no secrets or protocol data to ordinary stdout.

Your selected account data is necessarily returned to the model when you call a read tool. Review tool requests, especially write calls and upload_attachment_from_path.

1. Install

From this directory:

uv sync --python 3.12

uv.lock pins the tested dependency set. Dependencies are managed only with uv.

2. Create the Monzo client

1. Open Monzo Developer Tools and create an OAuth client.

2. Select Confidential as the client type.

3. Register this redirect URL exactly:

   http://127.0.0.1:8765/callback
   

4. Copy the client ID and client secret.

The redirect listener only runs while the authentication command is waiting. It binds to the loopback interface and validates an unguessable OAuth state value.

3. Store the client credentials

Private files let Codex and Claude share one credential source without putting the secret directly in both application configuration files:

mkdir -p ~/.config/monzo-mcp
chmod 700 ~/.config/monzo-mcp
read -r "MONZO_ID?Monzo client ID: "
print -rn -- "$MONZO_ID" > ~/.config/monzo-mcp/client-id
read -rs "MONZO_SECRET?Monzo client secret: "
print
print -rn -- "$MONZO_SECRET" > ~/.config/monzo-mcp/client-secret
unset MONZO_ID MONZO_SECRET
chmod 600 ~/.config/monzo-mcp/client-id ~/.config/monzo-mcp/client-secret

The commands above are for zsh, which is the default macOS shell. You can instead set MONZO_CLIENT_ID and MONZO_CLIENT_SECRET directly. Supported settings are:

Variable	Required	Default
MONZO_CLIENT_ID or MONZO_CLIENT_ID_FILE	Yes	—
MONZO_CLIENT_SECRET or MONZO_CLIENT_SECRET_FILE	Yes	—
MONZO_REDIRECT_URI	No	http://127.0.0.1:8765/callback
MONZO_TOKEN_PATH	No	~/.local/share/monzo-mcp/tokens.json
MONZO_REQUEST_TIMEOUT_SECONDS	No	30

MONZO_API_BASE_URL and MONZO_AUTH_BASE_URL also exist for tests; do not change them for normal use.

4. Authenticate once

MONZO_CLIENT_ID_FILE="$HOME/.config/monzo-mcp/client-id" \
MONZO_CLIENT_SECRET_FILE="$HOME/.config/monzo-mcp/client-secret" \
uv run monzo-mcp-auth

The command opens Monzo in your browser, receives the authorization code on localhost, exchanges it using the client secret, and stores the access and refresh tokens. Approve the notification in the Monzo mobile app before calling account tools.

Use uv run monzo-mcp-auth --no-browser to print the URL without opening it. Re-run the command if you revoke the grant or need Monzo's brief full-history access window.

5. Configure Codex

The quickest setup is the Codex CLI:

codex mcp add monzo \
  --env MONZO_CLIENT_ID_FILE="$HOME/.config/monzo-mcp/client-id" \
  --env MONZO_CLIENT_SECRET_FILE="$HOME/.config/monzo-mcp/client-secret" \
  --env MONZO_REDIRECT_URI="http://127.0.0.1:8765/callback" \
  --env MONZO_TOKEN_PATH="$HOME/.local/share/monzo-mcp/tokens.json" \
  -- /opt/homebrew/bin/uv run --directory /path/to/monzo-mcp monzo-mcp

Verify with codex mcp get monzo, then restart Codex. The equivalent TOML is in examples/codex-config.toml.

6. Configure Claude Desktop chat

On macOS, open Claude > Settings > Developer > Edit Config, or edit:

~/Library/Application Support/Claude/claude_desktop_config.json

Merge the monzo entry from examples/claude-desktop-config.json into the existing mcpServers object, then fully quit and reopen Claude Desktop. Absolute executable and project paths are intentional; GUI applications can have a smaller PATH than your terminal.

7. Configure Claude Code or the Claude Code desktop tab

Claude Desktop chat configuration is separate from Claude Code configuration. To add this server at user scope for Claude Code and its desktop Code tab:

claude mcp add \
  --transport stdio \
  --scope user \
  --env MONZO_CLIENT_ID_FILE="$HOME/.config/monzo-mcp/client-id" \
  --env MONZO_CLIENT_SECRET_FILE="$HOME/.config/monzo-mcp/client-secret" \
  --env MONZO_REDIRECT_URI="http://127.0.0.1:8765/callback" \
  --env MONZO_TOKEN_PATH="$HOME/.local/share/monzo-mcp/tokens.json" \
  monzo -- /opt/homebrew/bin/uv run --directory /path/to/monzo-mcp monzo-mcp

Verify with claude mcp get monzo. A project-scoped JSON example is in examples/claude-code.mcp.json; do not commit a version containing raw secrets.

Example requests

• “Use Monzo to show balances for my personal and joint accounts and their pots.”
• “Get a reconciliation snapshot from 2026-07-01 and group debits that look like bills.”
• “List transactions across all accounts for this month and show which recurring bills have already left.”
• “Compare these expected bills with my Monzo transactions, then total what is still outstanding: …”

The server supplies the financial facts; the model can compare them with the expected bill list you provide. It will not invent a schedule of bills that Monzo does not expose.

Development

uv run pytest
uv run ruff check .
uv run mypy

No live Monzo credentials are needed for the test suite. HTTP calls use the SDK's mock transport.

Troubleshooting

• No tokens found: run monzo-mcp-auth with the same credential and token paths used by the desktop client.
• 401 / invalid token: the server refreshes once automatically. If that fails, authenticate again; obtaining a new Monzo access token invalidates the old one for that client and user.
• 403 immediately after login: approve the pending access request in the Monzo mobile app.
• Server not visible: verify the absolute uv and project paths, then fully restart the desktop app. Claude Desktop chat and Claude Code use separate MCP configuration locations.
• Older transactions missing: Monzo limits history to 90 days after the first five minutes of authentication. Re-authenticate and request the older range promptly.
• Webhook receives nothing: Monzo must reach the registered URL from the internet. A localhost URL is not publicly reachable without a secure tunnel or receiver. This stdio server manages webhook registrations but does not expose a public webhook listener.