bunq MCP Server

An MCP server that lets AI assistants manage your bunq bank account.

Check balances, view transactions, send payments, request money — all through natural language in Claude, Cursor, or any MCP-compatible client.

Quick Start

npx bunq-mcp-server --api-key=YOUR_BUNQ_API_KEY

For development and testing, use the bunq sandbox:

npx bunq-mcp-server --api-key=YOUR_SANDBOX_API_KEY --environment=sandbox

What Can You Do With It?

Once connected, just talk to your AI assistant:

• "What's my account balance?" — lists all accounts with balances
• "Show me my last 10 transactions" — retrieves recent payments
• "Send €25 to NL02ABNA0123456789 for dinner" — sends a payment
• "Request €50 from [email protected] for concert tickets" — sends a payment request
• "Show me my recent card payments" — lists card transactions with merchant details
• "Create a draft payment of €100 to my landlord for approval" — creates a draft you approve in the bunq app

Setup

Getting a bunq API Key

Production:

1. Open the bunq app → Profile → Security & Settings → Developers → API Keys
2. Create a new API key
3. Copy the key — it will only be shown once

Sandbox (recommended for testing):

1. Generate a sandbox API key using the bunq sandbox API:

   curl -X POST https://public-api.sandbox.bunq.com/v1/sandbox-user-person \
     -H "Content-Type: application/json" \
     -H "X-Bunq-Client-Request-Id: unique-id" \
     -H "Cache-Control: none" \
     -H "X-Bunq-Geolocation: 0 0 0 0 000" \
     -H "X-Bunq-Language: en_US" \
     -H "X-Bunq-Region: nl_NL"

2. The response contains an ApiKey field — use that as your --api-key
3. Sandbox accounts come with test funds, so you can safely test payments

Client Configuration

Claude Desktop / Claude Code

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "bunq": {
      "command": "npx",
      "args": ["-y", "bunq-mcp-server", "--api-key=YOUR_BUNQ_API_KEY"]
    }
  }
}

Cursor / Windsurf / VS Code (GitHub Copilot)

Add to your editor's MCP settings (Cursor MCP config, Windsurf MCP config, or .vscode/mcp.json):

{
  "mcpServers": {
    "bunq": {
      "command": "npx",
      "args": ["-y", "bunq-mcp-server"],
      "env": {
        "BUNQ_API_KEY": "YOUR_BUNQ_API_KEY"
      }
    }
  }
}

Note: VS Code uses "servers" instead of "mcpServers" as the top-level key.

Configuration

| Variable / CLI Flag | Required | Default | Description | |---|---|---|---| | BUNQ_API_KEY / --api-key | Yes | — | bunq API key | | BUNQ_ENVIRONMENT / --environment | No | production | sandbox or production | | BUNQ_API_CONTEXT_PATH / --context-path | No | ~/.bunq/api-context.json | Path to persist API context | | BUNQ_LOG_LEVEL | No | info | Log verbosity: debug, info, warn, error |

CLI flags take precedence over environment variables.

Tip: If you encounter persistent authentication errors, delete the cached context and restart: rm ~/.bunq/api-context.json

Available Tools

Read-only

| Tool | Description | |---|---| | bunq_get_user | Get current user profile and account holder details | | bunq_list_monetary_accounts | List all monetary accounts (bank, savings, joint) with balances | | bunq_get_monetary_account | Get details of a specific monetary account | | bunq_list_payments | List payments for a monetary account (supports pagination) | | bunq_get_payment | Get details of a specific payment | | bunq_get_mastercard_action | Get card transaction details (merchant, location, card info) | | bunq_list_mastercard_actions | List card transactions for a monetary account (supports pagination) | | bunq_list_events | List recent account events and notifications | | bunq_list_request_inquiries | List payment requests sent from a monetary account (supports pagination) | | bunq_get_request_inquiry | Get details of a specific payment request | | bunq_health_check | Verify the bunq API connection is working |

Write

| Tool | Description | |---|---| | bunq_create_payment | Send a payment via IBAN, email, or phone (irreversible) | | bunq_create_draft_payment | Create a draft payment requiring approval in the bunq app | | bunq_create_payment_request | Send a payment request (invoice) via IBAN, email, or phone |

Write tools are annotated with destructiveHint: true so AI assistants will ask for confirmation before executing. Draft payments additionally require explicit approval in the bunq mobile app.

How It Works

The server handles bunq API authentication automatically — RSA key generation, device registration, and session management. Credentials are persisted locally so you don't re-register on every restart, and sessions refresh transparently when they expire.

Security

• API keys and tokens are never logged — stdout is reserved for MCP protocol
• Credential file stored with 0600 permissions (owner-only)
• All API requests signed with RSA-SHA256
• Input validation on IBAN, email, and phone formats before any API call
• API key format validated on startup
• 30-second request timeout on all HTTP calls
• Rate limiting (429) handled gracefully with retry guidance

Development

npm install          # Install dependencies
npm run dev          # Run with tsx (auto-reload)
npm run build        # Bundle with tsup to dist/
npm test             # Run Vitest
npm run typecheck    # Run TypeScript type checking
npm run lint         # Run ESLint
npm run format:check # Check Prettier formatting
npm run inspect      # Run with MCP Inspector for manual testing

Requires Node.js 20+.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Use Conventional Commits for commit messages
4. Ensure npm run typecheck, npm run lint, npm run format:check, and npm test pass
5. Open a pull request

Acknowledgements

Inspired by Stripe Agent Toolkit, Razorpay MCP Server, and Plaid MCP Server.

License

MIT