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 john@example.com 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 monetary accounts (bank, savings, joint) with balances (supports pagination)
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