# Qonto MCP Server

A remote [Model Context Protocol](https://modelcontextprotocol.io) server for the [Qonto](https://qonto.com) 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](https://nodejs.org) 18+
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) (`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

```bash
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](https://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

```bash
npx wrangler kv namespace create "OAUTH_KV"
```

Copy the returned ID into `wrangler.jsonc`:

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

### 4. Set secrets

```bash
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:

```bash
cp .dev.vars.example .dev.vars
```

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

### 6. Deploy

```bash
npm run deploy
```

## Connecting to Claude Desktop

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

```json
{
  "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