monzo-mcp

A TypeScript MCP server for interacting with the Monzo API from Claude Desktop or any other MCP client.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants discover and call tools exposed by local or remote servers. In this project, Claude Desktop launches a local Node.js process, sends JSON-RPC messages over standard input/output, and that process turns tool calls into HTTPS requests to Monzo.

+----------------+      JSON-RPC over stdio      +----------------+      HTTPS      +-----------+
| Claude Desktop | <---------------------------> | Monzo MCP      | <------------> | Monzo API |
| (MCP client)   |                               | Server         |                |           |
+----------------+                               +----------------+                +-----------+

Setup

1. Clone the repo.

2. Install dependencies:

   npm install
   

3. Create a Monzo developer app at https://developers.monzo.com.

   • Set the redirect URI to http://localhost:3000/callback
   • Set the client type to confidential

4. Copy .env.example to .env and fill in your client ID and client secret.

   cp .env.example .env
   

5. Complete the OAuth flow.

   Visit this exact authorization URL after replacing YOUR_CLIENT_ID:

   https://auth.monzo.com/?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/callback&response_type=code&state=random123
   

   Approve access in Monzo. Monzo redirects back to:

   http://localhost:3000/callback?code=YOUR_AUTH_CODE&state=random123
   

   Copy the code value and exchange it for tokens:

   curl --request POST https://api.monzo.com/oauth2/token \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=authorization_code' \
     --data-urlencode 'client_id=YOUR_CLIENT_ID' \
     --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
     --data-urlencode 'redirect_uri=http://localhost:3000/callback' \
     --data-urlencode 'code=YOUR_AUTH_CODE'
   

   Copy the returned access_token and refresh_token into .env. The server will also persist refreshed tokens into tokens.json automatically.

Building and running

Build the server:

npm run build

Run it manually if you want to test stdio startup:

npm start

Adding to Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS:

{
  "mcpServers": {
    "monzo": {
      "command": "node",
      "args": [
        "/absolute/path/to/monzo-mcp/dist/index.js"
      ]
    }
  }
}

Replace /absolute/path/to/monzo-mcp/dist/index.js with your real path after building. The server reads .env from the repository root, so you can keep secrets out of the Claude Desktop config file.

Available tools

Tool	Description
list_accounts	List Monzo accounts available to the authenticated user.
get_balance	Read the available balance, total balance, and today's spend for an account.
list_transactions	List transactions for an account with optional date filters and limit.
get_transaction	Fetch the full details for a specific transaction.
annotate_transaction	Add a note to a transaction's metadata.
search_transactions	Fetch up to 100 transactions and filter by merchant or description locally.
list_pots	List pots linked to an account.
deposit_to_pot	Move money from an account into a pot.
withdraw_from_pot	Move money from a pot back into an account.

Security notes

• OAuth tokens are stored in tokens.json, which is gitignored.
• Never commit .env or real tokens.
• This MCP server is intended to run locally on your machine.
• For personal use, local disk token storage is standard; production deployments should use a proper secrets manager.