Qonto 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 [email protected]: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