open-banking-mcp

An MCP server that gives Claude read-only access to UK bank accounts through TrueLayer's Data API — one integration covering Monzo, Starling, HSBC, Barclays, Lloyds, NatWest, Nationwide, Santander and most other UK banks.

Read-only by design: this server requests Data API scopes only. There is no code path here that can move money.

Status: working against both the sandbox and a real bank connection. Single-user, personal-scale; not hardened for multi-tenant use.

Install

git clone https://github.com/pimvanoerle/open-banking-mcp.git
cd open-banking-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

On an Intel Mac, that install fails while building cryptography unless you have a Rust toolchain — upstream dropped macOS x86_64 wheels at version 49. Use the bundled constraints file instead:

.venv/bin/pip install -e ".[dev]" -c constraints-macos-intel.txt

That pin is deliberately not in pyproject.toml, so everyone else keeps getting current cryptography security updates.

Related MCP server: Bank

Setup

1. Create a TrueLayer app

1. Sign up at console.truelayer.com — free, instant, Google/GitHub SSO or email.

2. New accounts start in sandbox, which is where you want to begin: a mock bank, no rate limits, no real money.

3. Click Create App + and choose a client id — 4–30 lowercase letters and digits. It cannot be changed later. Sandbox ids get a sandbox- prefix automatically; the live id is the same name without it.

4. Copy the client secret — shown once. More can be minted later under Settings (up to 6 at a time).

5. Add a redirect URI of http://localhost:8080/callback. It must match byte for byte, scheme and path included — a mismatch is TrueLayer's own documented most-common cause of auth failures.

2. Configure

Copy .env.example to .env and fill it in:

TRUELAYER_CLIENT_ID=sandbox-yourapp
TRUELAYER_CLIENT_SECRET=...
TRUELAYER_REDIRECT_URI=http://localhost:8080/callback
TRUELAYER_ENV=sandbox

Load it before running commands:

set -a; . ./.env; set +a

Every .env* file is gitignored except .env.example.

3. Connect a bank

open-banking-mcp auth

This opens a browser for consent and stores the tokens in your OS keychain.

In the sandbox, pick the mock bank and log in as john / doe — john1/doe1 through john100/doe100 give different account shapes. The sandbox reports its provider id as mock, not uk-cs-mock, so that's the name status and logout expect.

open-banking-mcp status                 # connected banks + consent countdown
open-banking-mcp logout ob-santander-personal

4. Going live

The console has a Sandbox / Live toggle. The same app exists in both, but they are separate environments: separate client ids, separate secrets, separate redirect URI registrations. Register your callback again on the Live side — it does not carry over.

Keep live credentials in their own file:

cp .env.example .env.production
# fill in the live client id and secret, set TRUELAYER_ENV=production
set -a; . ./.env.production; set +a
open-banking-mcp auth

New secrets can take up to 15 minutes to become active. If the first attempt fails with a 400, wait before assuming something is broken.

Sandbox and production data never mix. Tokens are keyed by environment in the keychain, the provider index is grouped by environment, and each environment gets its own cache file. Without that separation, a mock bank's balance could be reported as real money.

How it reads data

Every read is served from a local SQLite cache by default, refreshed by a daily sync. This is not just a speed trick: TrueLayer caches responses for an hour and throttles unattended callers hard unless the request carries an X-PSU-IP header saying a human is present. An agent checking your accounts on a schedule is exactly the throttled case, so it reads locally instead.

open-banking-mcp sync     # pull everything; run this daily
open-banking-mcp cache    # what's stored, and when it last synced

Every response says how old it is:

{
  "data": { "current": 4049.13, "available": 7049.13, "currency": "GBP" },
  "as_of": "2026-09-13T06:43:52Z",
  "age": "3 hours old",
  "source": "cache",
  "stale": false
}

Past TRUELAYER_MAX_AGE_HOURS (default 25 — a daily sync plus slack) stale flips to true and a warning field is added, so an agent reporting a balance can say how current it is rather than implying it is live.

When you need live figures — you just sent a payment and want to know whether it landed — every read tool takes fresh=true, which bypasses the cache, queries the bank, and writes the result back:

get_balance(account_id="...", fresh=true)
get_transactions(account_id="...", fresh=true)   # also pulls pending

fresh=true on transactions needs a specific account_id: a live refresh is per-account, not a whole-portfolio sweep, which is precisely the pattern that trips the rate limiter. It pulls pending transactions too — usually what "did my payment go through" actually means.

If TrueLayer does throttle you, a sync stops at the first 429 rather than walking the remaining accounts; continuing would burn the rest of the allowance and fail anyway. Whatever synced before the limit stays cached.

Scheduling the daily sync

17 6 * * *  cd ~/dev/openbanking-mcp && set -a && . ./.env.production && set +a && .venv/bin/open-banking-mcp sync >> ~/.open-banking-mcp/sync.log 2>&1

MCP tools

All except list_banks, sync_now and cache_status accept fresh.

Connecting it to Claude

{
  "mcpServers": {
    "open-banking": {
      "command": "/absolute/path/to/.venv/bin/open-banking-mcp-server",
      "env": {
        "TRUELAYER_CLIENT_ID": "yourapp",
        "TRUELAYER_CLIENT_SECRET": "...",
        "TRUELAYER_ENV": "production"
      }
    }
  }
}

Security

This server holds credentials and a mirror of your financial history. What that means in practice:

Read-only. The requested scopes are info accounts balance transactions cards direct_debits standing_orders offline_access — all Data API. There are no payment scopes and no payment endpoints in this codebase. The worst case is data exposure, not money movement.

On disk, under ~/.open-banking-mcp/ (directory mode 0700):

SQLite journal and WAL side-car files are restricted too; they hold the same data as the database.

Tokens go in the OS keychain by default (service open-banking-mcp, account <env>:<provider_id>). The plaintext provider index exists because keyrings cannot be enumerated. Set TRUELAYER_TOKEN_FILE for a 0600 JSON file instead, on Linux or CI with no keyring daemon; the server falls back to this automatically when it finds no usable keyring backend.

Client secrets belong in .env / .env.production, never in the repo, never in a shell history, never pasted into a chat. If one leaks, rotate it in the console — your bank connection survives, because the refresh token is already issued.

Consider where the data ends up. If you wire this into a chat assistant, your balances and transactions travel wherever that assistant's messages go. That's a deliberate decision worth making up front.

Revoking access is always available from your banking app or TrueLayer, and consent expires on its own after 90 days.

Consent expiry

Open Banking consent lasts 90 days under FCA rules, then you must re-authorise in a browser — there is no way around this. status shows the countdown per bank, amber at 21 days and red at 7.

Note that a refresh response often omits refresh_token entirely rather than rotating it. The client carries the existing one forward when that happens; dropping it would break every subsequent refresh.

Development

.venv/bin/pytest            # 63 tests, no network required

Tests mock TrueLayer's HTTP endpoints, so the suite runs offline. The interactive OAuth flow is covered end to end by driving the real localhost callback server with a fake browser.

Licence

MIT