README.md•5.02 kB
# Bunq MCP
A Model Context Protocol server for Bunq (Dutch neo bank).
## Available Tools
This MCP server provides the following tools for interacting with Bunq:
1. **bunqAccounts** - Get your Bunq accounts with details like account type, balance, and ID
2. **getTransactions** - View transactions (payments) for a specific account
3. **getRequestInquiries** - Get money requests you've sent from a specific account
4. **createPaymentRequest** - Create a payment request to receive money into your account
5. **getPaymentAutoAllocates** - Get automatic payment allocation settings for an account
6. **getTopCounterparties** - Get a list of unique person counterparties based on recent transactions
7. **createDraftPayment** - Create draft payments with optional scheduling (requires review / approval in
the app before execution)
8. **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](https://doc.bunq.com/basics/authentication) for more information.
Creating an API key or OAuth client is done through the Bunq app:
1. Press your face on the top left
2. Press the cog in the top right
3. Under "Developers", either go to "OAuth" or "API Keys".
4. 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
1. Install the `bunq-mcp` and `mcp-remote` CLI tools:
```sh
npm install -g bunq-mcp mcp-remote
```
2. In the Bunq app, create an OAuth client or API key (see above).
3. (Optional) Generate a new public/private key pair:
```sh
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.
4. Start the MCP server in any terminal:
```sh
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.
5. In your favourite editor or other MCP client (such as Claude Desktop), add the following:
```json
{
"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](https://github.com/geelen/mcp-remote) for
more information.
6. 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
1. Create `.dev.vars` file in the root directory with the following content:
```sh
# 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=
```
2. Start development server
```sh
npm run dev
```
3. Setup MCP configuration
```json
{
"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.
```json
{ "Error": [{ "error_description": "Not enough permissions to create payment." }] }
```