README - Bunq MCP by wilcokruijer

Bunq MCP

A Model Context Protocol server for Bunq (Dutch neo bank).

Screenshot

Available Tools

This MCP server provides the following tools for interacting with Bunq:

bunqAccounts - Get your Bunq accounts with details like account type, balance, and ID
getTransactions - View transactions (payments) for a specific account
getRequestInquiries - Get money requests you've sent from a specific account
createPaymentRequest - Create a payment request to receive money into your account
getPaymentAutoAllocates - Get automatic payment allocation settings for an account
getTopCounterparties - Get a list of unique person counterparties based on recent transactions
createDraftPayment - Create draft payments with optional scheduling (requires review / approval in the app before execution)
createPayment - Create real-money payments (transfers immediately). Only available when using an API key (not OAuth).

These tools can be accessed through any MCP client connected to this server.

Authentication

This server supports two modes of authentication: OAuth and API Key. See the Bunq documentation for more information.

Creating an API key or OAuth client is done through the Bunq app:

Press your face on the top left
Press the cog in the top right
Under "Developers", either go to "OAuth" or "API Keys".
If using OAuth set the redirect URL to the following:
```
http://localhost:8788/callback
```

(Modify the port if needed.)

When starting the server, you can either set the BUNQ_CLIENT_ID and BUNQ_CLIENT_SECRET environment variables, or the BUNQ_API_KEY environment variable. Alternatively, you can pass the client ID and secret or API key as command line arguments: --bunq-client-id <id> --bunq-client-secret <secret> or --bunq-api-key <key>.

Note: If you want to create actual real-money non-draft payments, you need to use an API key.

Installation & Usage

Install the bunq-mcp and mcp-remote CLI tools:

npm install -g bunq-mcp mcp-remote

In the Bunq app, create an OAuth client or API key (see above).
(Optional) Generate a new public/private key pair:

bunq-mcp --generate-keys

Note this assumes openssl is installed & available on the PATH. If you decide to skip this step, pre-existing keys in ./src/keys/ will be used. The created keys will override the pre-existing keys and are stored in the global node_modules directory.

Start the MCP server in any terminal:

bunq-mcp --mcp --bunq-client-id <client-id> --bunq-client-secret <client-secret>

Client ID and secret can also be set using the BUNQ_CLIENT_ID and BUNQ_CLIENT_SECRET environment variables.

In your favourite editor or other MCP client (such as Claude Desktop), add the following:

{
  "mcpServers": {
    "bunq-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8788/sse"]
    }
  }
}

Again, modify the port if needed. mcp-remote is used because this package uses the SSE transport, while most clients do not support that. See mcp-remote for more information.

As soon as the MCP server is started, mcp-remote should open your browser to start the OAuth flow.

You should now be able to ask a question, such as

What's my current Bunq balance?
What are my top 5 counterparties?
What was my last transaction?

Troubleshooting

If there's any issue with the OAuth flow, you can try to delete the directory created by mcp-remote in your home directory: rm -rf ~/.mcp-auth.

CLI

Usage: bunq-mcp [options]

Options:
  --help              Show help
  --version           Show version
  --generate-keys     Generate private and public key pair for Bunq installation
  --mcp               Start MCP server
  --host <host>       Host (for MCP server)
  --port <port>       Port (for MCP server)
  --bunq-client-id <id>         Bunq client ID (alternative to BUNQ_CLIENT_ID env var)
  --bunq-client-secret <secret> Bunq client secret (alternative to BUNQ_CLIENT_SECRET env var)
  --bunq-api-key <key>          Bunq API key (alternative to BUNQ_API_KEY env var)

Development

Create .dev.vars file in the root directory with the following content:

# When set to 1 the public/private key pair in this repo is used.
IS_DEVELOPMENT=1

# Create OAuth client in the Bunq app
BUNQ_CLIENT_ID=
BUNQ_CLIENT_SECRET=

Start development server

npm run dev

Setup MCP configuration

{
  "mcpServers": {
    "bunq-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8788/sse"]
    }
  }
}

Limitations

It's not possible to create payments using the OAuth flow. Only draft payments can be created.

{ "Error": [{ "error_description": "Not enough permissions to create payment." }] }