# 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.

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

## Setup

1. Clone the repo.
2. Install dependencies:

   ```bash
   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.

   ```bash
   cp .env.example .env
   ```

5. Complete the OAuth flow.

   Visit this exact authorization URL after replacing `YOUR_CLIENT_ID`:

   ```text
   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:

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

   Copy the `code` value and exchange it for tokens:

   ```bash
   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:

```bash
npm run build
```

Run it manually if you want to test stdio startup:

```bash
npm start
```

## Adding to Claude Desktop

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

```json
{
  "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.