🏦 bank-mcp

Give your AI assistant secure, read-only access to your bank accounts.

Most people manage their finances by logging into bank portals, downloading CSVs, and building spreadsheets. bank-mcp eliminates that friction by letting your AI assistant query your bank accounts directly — balances, transactions, spending breakdowns — through natural conversation. It connects to real bank APIs via the Model Context Protocol so any MCP-compatible client (Claude Code, Claude Desktop, and others) can understand your finances.

• 5 providers, 15,000+ institutions — US and European banks covered

• Read-only by design — no write access, no transfers, no modifications

• Works with any MCP client — Claude Code, Claude Desktop, Cursor, and more

• Pluggable architecture — add your own provider in under 100 lines

Table of Contents

• Supported Providers

• Quick Start

• Client Setup

• Available Tools

• Architecture

• Provider Setup Guides

• Caching

• Multiple Connections

• Security

• Adding a New Provider

• Troubleshooting

• Development

• Contributing

• License

Supported Providers

US Banks

Supported through Plaid and Teller — covering the top 20 US institutions and thousands more:

JPMorgan Chase · Bank of America · Wells Fargo · Citibank · Capital One · U.S. Bank · PNC · Truist · Goldman Sachs · TD Bank · Citizens · Fifth Third · M&T Bank · Huntington · KeyBank · Ally · Regions · BMO · American Express · USAA

European Banks

Supported through Enable Banking and Tink — covering major banks across the EU and UK:

HSBC · BNP Paribas · Deutsche Bank · ING · Crédit Agricole · Santander · Société Générale · UniCredit · Intesa Sanpaolo · Barclays · Lloyds · BBVA · CaixaBank · Commerzbank · Rabobank · ABN AMRO · Swedbank · Handelsbanken · Nordea · PKO Bank Polski

Quick Start

1. Configure a bank connection

The interactive wizard walks you through selecting a provider and entering credentials. It validates your connection by fetching accounts before saving.

2. Add to your MCP client

Add bank-mcp to your AI tool's MCP configuration. Here's the most common setup:

Claude Code (.mcp.json in your project root or ~/.claude/.mcp.json globally):

Using a different tool? See Client Setup for Claude Desktop, Cursor, VS Code, Windsurf, Codex CLI, Gemini CLI, and Zed.

3. Try it

Ask your AI assistant about your finances in natural language:

Demo Mode

Don't have bank credentials yet? Start with realistic fake data:

This launches with a mock provider that generates deterministic sample accounts and transactions — perfect for testing your setup or building on top of bank-mcp before connecting real accounts.

Client Setup

bank-mcp works with any MCP-compatible client. Pick your tool below.

Claude Code

Add to .mcp.json in your project root (or ~/.claude/.mcp.json for all projects):

Or add via the CLI:

Claude Desktop

Add to your claude_desktop_config.json:

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

VS Code (Copilot)

Add to .vscode/mcp.json in your workspace:

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

OpenAI Codex CLI

Add to ~/.codex/config.toml (or .codex/config.toml in your project):

Or add via the CLI:

Gemini CLI

Add to ~/.gemini/settings.json (or .gemini/settings.json in your project):

Zed

Add to your Zed settings.json:

Don't see your tool? bank-mcp uses standard MCP stdio transport. Any client that supports MCP stdio servers can connect using npx @bank-mcp/server as the command.

Available Tools

Example Conversations

Here's what real interactions look like:

Checking balances:

You: What's in my bank accounts?

Claude: You have 3 accounts across 2 connections:

Account	Balance	Available
ING Checking	€3,241.50	€3,141.50
ING Savings	€12,800.00	€12,800.00
Revolut Main	€891.23	€891.23

Spending analysis:

You: Show my spending by category this month

Claude: Here's your spending breakdown for February 2026:

Category	Amount	Transactions
Groceries	€487.30	12
Restaurants	€213.50	8
Transport	€156.00	5
Subscriptions	€89.97	4

Searching transactions:

You: Find all Amazon purchases over $50 in the last 3 months

Claude: Found 7 Amazon transactions over $50 since November:

• Dec 15: Amazon.com — $129.99 (Electronics)

• Dec 3: Amazon.com — $67.50 (Books)

• ...

Architecture

File Structure

Provider Interface

Every provider extends the same abstract class, making it straightforward to add new integrations:

Provider Setup Guides

Enable Banking (PSD2)

What you need:

• An Enable Banking account with a registered app

• Your RSA private key (.pem file)

• An active session ID from the OAuth consent flow

Tip: Sessions expire after 90 days (PSD2 regulation). You'll need to re-authenticate through the consent flow periodically. The server logs a clear message when a session expires.

Teller (US Banks)

What you need:

• A Teller developer account

• Your client certificate and private key (.zip download from the Teller dashboard)

• An access token from a Teller Connect enrollment

Tip: Teller uses mutual TLS (mTLS) — your app authenticates at the TLS layer via client certificate, then individual enrollments authenticate via access token. Free tier supports up to 100 live connections.

Plaid (US/CA/EU)

What you need:

• A Plaid developer account (free signup)

• Your Client ID and Secret (from the Plaid dashboard)

• An access token from a Plaid Link enrollment

Tip: Start with the sandbox environment (fake data, instant setup). Plaid provides the richest transaction categorization — 104 sub-categories with confidence scores — which makes it ideal for LLM-driven spending analysis.

Tink (EU Open Banking)

What you need:

• A Tink developer account (free for testing)

• An OAuth2 access token (from the Tink Console or your OAuth2 flow)

Tip: Tink covers 3,400+ banks across Europe. Transactions include PFM (Personal Finance Management) categories with merchant enrichment, and amounts use fixed-point decimals — no floating-point rounding surprises.

Caching

All data is cached in-memory (no disk persistence — cache dies with the process):

Cache is per-connection and per-account. Restarting the server clears all caches.

Multiple Connections

Configure as many bank connections as you need — even across different providers:

All tools accept an optional connectionId parameter to target a specific connection. When omitted, every connection is queried and results are merged — so "show all my balances" works across banks automatically.

Security

Design Principles

bank-mcp handles sensitive financial credentials. Its security posture is built on minimizing attack surface:

• Read-only by design — the BankProvider interface exposes only read methods (listAccounts, listTransactions, getBalance). There are no write methods — no transfers, no account modifications, no payment initiation. This is enforced at the type level, not by convention.

• No network listener — bank-mcp runs as a stdio process (stdin/stdout), not an HTTP server. There is no open port, no attack surface from the network.

• Minimal dependencies — only 3 runtime dependencies (@modelcontextprotocol/sdk, jsonwebtoken, zod). Fewer dependencies means fewer supply chain risks.

• Open source — every line is auditable. No obfuscated code, no compiled blobs, no telemetry.

Credential Storage

• Config file at ~/.bank-mcp/config.json is created with 600 (owner read/write only)

• RSA keys and certificates are stored in ~/.bank-mcp/keys/ with the same restrictive permissions

• Credentials are never logged — the server sanitizes config objects before any debug output

• No credential caching beyond the process lifetime — when the server stops, credentials exist only on disk

Data Flow

• Transaction data flows directly from your bank's API to your local MCP client

• Nothing is stored remotely — no cloud relay, no proxy server, no intermediate storage

• No telemetry — zero analytics, no crash reports, no usage tracking, no phone-home

• In-memory cache is per-process and dies when the server stops

What Your MCP Client Sees

The MCP client (Claude, Cursor, etc.) receives structured tool results containing:

• Account names, types, and balances

• Transaction descriptions, amounts, dates, and categories

• Spending summaries

The LLM processes this in its context window. Be aware that cloud-hosted LLMs send your conversation (including tool results) to their servers. If this is a concern, use a local model or review your provider's data retention policy.

Recommendations

• Rotate tokens — if your banking provider supports token rotation, enable it

• Use sandbox first — test your setup with mock data or Plaid sandbox before connecting live accounts

• Review permissions — ensure ~/.bank-mcp/ is not world-readable (ls -la ~/.bank-mcp/)

• Scope access — if your provider supports it, request the minimum scopes needed (read-only account and transaction access)

Reporting Vulnerabilities

If you discover a security issue, please email the maintainer directly rather than opening a public issue. See CONTRIBUTING.md for contact details.

Adding a New Provider

The pluggable architecture makes it straightforward to add support for additional banking APIs:

1. Create your provider at src/providers/your-provider/index.ts

2. Extend — implement listAccounts, listTransactions, getBalance, and getConfigSchema

3. Register it in src/providers/registry.ts

4. Add config fields for the init wizard (the schema drives the interactive prompts automatically)

See src/providers/enable-banking/ as a reference implementation. The mock provider at src/providers/mock/ is also useful for understanding the expected data shapes.

Troubleshooting

npx

npx caches packages. Force the latest:

"Permission denied" reading config

The config file should be readable by your user:

"Session expired" (Enable Banking)

PSD2 sessions expire after 90 days. Re-run the init wizard:

Tools not showing up in your MCP client

1. Verify the server starts: npx @bank-mcp/server --mock (should output MCP protocol on stdout)

2. Check your config file path matches your client's expected location

3. Restart your MCP client after adding the config

4. Check your client's MCP logs for connection errors

"ETLS" or certificate errors (Teller)

Teller requires mTLS. Verify your certificate files:

Development

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

If you're adding a new provider, open an issue first to discuss the approach — we want to make sure the integration fits the project's architecture.

License

MIT — use it however you want.