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:
- Open the bunq app → Profile → Security & Settings → Developers → API Keys
- Create a new API key
- Copy the key — it will only be shown once
Sandbox (recommended for testing):
- 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" - The response contains an
ApiKeyfield — use that as your--api-key - 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
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
Write
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
0600permissions (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
- Fork the repository
- Create a feature branch (
git checkout -b feat/my-feature) - Use Conventional Commits for commit messages
- Ensure
npm run typecheck,npm run lint,npm run format:check, andnpm testpass - Open a pull request
Acknowledgements
Inspired by Stripe Agent Toolkit, Razorpay MCP Server, and Plaid MCP Server.