Qonto MCP Server

Qonto MCP Server

A remote Model Context Protocol server for the Qonto API, deployed on Cloudflare Workers with GitHub OAuth authentication.

Features

• 21 tools covering the full Qonto API v2: organization, transactions, attachments, beneficiaries, clients, invoices, labels, memberships, requests, statements, and transfers
• OAuth 2.1 authentication via GitHub (Authorization Code + PKCE)
• Stateful sessions via Cloudflare Durable Objects
• Zero cold-start secrets — Qonto credentials never leave Cloudflare

Tools

| Category | Tools | |---|---| | Organization | get_qonto_organization | | Transactions | get_qonto_transactions, get_qonto_transaction, list_qonto_transaction_attachments | | Attachments | get_qonto_attachment | | Beneficiaries | list_qonto_beneficiaries, get_qonto_beneficiary | | Clients | get_clients, get_client | | Invoices | get_client_invoices, get_supplier_invoices, get_credit_notes | | Labels | list_qonto_labels, get_qonto_label | | Memberships | list_qonto_memberships | | Requests | get_requests, get_request | | Statements | get_statements, download_statement | | Transfers | list_qonto_external_transfers, get_qonto_external_transfer |

Prerequisites

• Node.js 18+
• Wrangler CLI (npm install -g wrangler)
• A Cloudflare account
• A Qonto account with API access (Settings → Integrations → API)
• A GitHub OAuth App

Setup

1. Clone and install

git clone git@github.com:thomas-rx/qonto-mcp-worker.git
cd qonto-mcp-worker
npm install

2. Create a GitHub OAuth App

Go to github.com/settings/developers → OAuth Apps → New OAuth App.

| Field | Value | |---|---| | Homepage URL | https://<worker-name>.<account>.workers.dev | | Authorization callback URL | https://<worker-name>.<account>.workers.dev/callback |

For local development, create a second app with http://localhost:8788 and http://localhost:8788/callback.

3. Create the KV namespace

npx wrangler kv namespace create "OAUTH_KV"

Copy the returned ID into wrangler.jsonc:

"kv_namespaces": [{ "binding": "OAUTH_KV", "id": "<your-id>" }]

4. Set secrets

npx wrangler secret put QONTO_API_KEY
npx wrangler secret put QONTO_ORGANIZATION_ID
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY

5. Local development

Copy .dev.vars.example to .dev.vars and fill in your credentials:

cp .dev.vars.example .dev.vars

npm run dev
# → http://localhost:8788

6. Deploy

npm run deploy

Connecting to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "qonto": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<worker-name>.<account>.workers.dev/<mcp-path>"
      ]
    }
  }
}

On first connection, a browser window will open for GitHub authentication. Sessions persist for 30 days.

Architecture

Request → OAuthProvider
            ├── /authorize   → GitHub OAuth consent flow
            ├── /callback    → Token exchange + Qonto session
            ├── /token       → OAuth token endpoint
            ├── /register    → Dynamic client registration
            └── /<mcp-path>  → QontoMCP (Durable Object)
                                └── QontoClient → Qonto API v2

Environment Variables

| Variable | Required | Description | |---|---|---| | QONTO_API_KEY | Yes | Qonto secret key | | QONTO_ORGANIZATION_ID | Yes | Qonto organization slug | | QONTO_THIRDPARTY_HOST | No | Override API base URL (default: https://thirdparty.qonto.com) | | QONTO_STAGING_TOKEN | No | Qonto staging token | | GITHUB_CLIENT_ID | Yes | GitHub OAuth App client ID | | GITHUB_CLIENT_SECRET | Yes | GitHub OAuth App client secret | | COOKIE_ENCRYPTION_KEY | Yes | 32-byte hex key for signing cookies |

License

MIT