io.github.alexey-pelykh/qontoctl

CLI and MCP server for the Qonto banking API.

This project is brought to you by Alexey Pelykh.

What It Does

QontoCtl lets AI assistants (Claude, etc.) interact with Qonto through the Model Context Protocol. It can:

• Organizations — retrieve organization details and settings
• Accounts — list, create, update, close bank accounts; download IBAN certificates
• Transactions — list, search, filter bank transactions; manage transaction attachments
• Bank Statements — list, view, and download bank statements
• Labels — manage transaction labels and categories
• Memberships — view team members, show current membership, invite new members
• SEPA Beneficiaries — list, add, update, trust/untrust SEPA beneficiaries
• SEPA Transfers — list, create, cancel transfers; download proofs; verify payees
• Internal Transfers — create transfers between accounts in the same organization
• Bulk Transfers — list and view bulk transfer batches
• Recurring Transfers — list and view recurring transfers
• Terminals (POS) — list Qonto Terminals and initiate terminal payments
• Products — list catalogue products
• Clients — list, create, update, delete clients
• Client Invoices — full lifecycle: create, update, finalize, send, mark paid, cancel, upload files
• Quotes — create, update, delete, send quotes
• Credit Notes — list and view credit notes
• Supplier Invoices — list, view, and bulk-create supplier invoices
• Requests — list organization requests
• Attachments — upload and view attachments
• E-Invoicing — retrieve e-invoicing settings

Prerequisites

• Node.js >= 24
• A Qonto business account with API access

Installation

npm install -g qontoctl

Or run directly with npx:

npx qontoctl --help

Or install via Homebrew:

brew install qontoctl/tap/qontoctl

Quick Start

# 1. Install
npm install -g qontoctl

# 2. Create a profile with your Qonto API credentials
qontoctl profile add mycompany

# 3. Test the connection
qontoctl profile test --profile mycompany

# 4. List your accounts
qontoctl account list --profile mycompany

MCP Integration

QontoCtl implements the Model Context Protocol (MCP), letting AI assistants interact with your Qonto account through natural language.

MCP Client Configuration

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"]
        }
    }
}

claude mcp add qontoctl -- npx qontoctl mcp

Add to .cursor/mcp.json in your project root:

{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"]
        }
    }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"]
        }
    }
}

Pointing MCP at a non-default config file

The MCP server has no CLI flags. To load credentials from a config file other than ~/.qontoctl.yaml, set QONTOCTL_CONFIG_FILE in the host's env block:

{
    "mcpServers": {
        "qontoctl": {
            "command": "npx",
            "args": ["qontoctl", "mcp"],
            "env": {
                "QONTOCTL_CONFIG_FILE": "/abs/path/to/qontoctl.yaml",
            },
        },
    },
}

The path is captured at server startup. See docs/configuration.md for the full resolution chain.

Available MCP Tools

Example Prompts

Once configured, you can ask your AI assistant things like:

• "Show my Qonto account balances"
• "List recent transactions over 1000 EUR"
• "What were last month's card payments?"
• "Show all team members in my organization"
• "List bank statements for January 2026"
• "Create a summary of this week's debits"

SCA Continuation

Some Qonto write operations — creating a transfer, modifying a card, approving a request — require Strong Customer Authentication (SCA): the user has to approve the request in the Qonto mobile app before it executes. QontoCtl wraps every SCA-gated MCP write tool with a continuation flow so the LLM client never has to reimplement polling.

How a wrapped write tool behaves

When an SCA-gated tool (e.g. transfer_create, card_create, beneficiary_trust, request_approve) hits a 428 SCA challenge, the wrapper polls the SCA session inline. If the user approves within the polling window, the tool returns the operation's success result transparently — the LLM never sees the SCA round-trip. If polling times out (or polling is disabled), the tool returns a structured SCA-pending response carrying the session token and instructions to continue.

Every wrapped tool exposes two optional input fields for this flow:

• wait — maximum seconds to poll inline before falling back to the pending response.
• sca_session_token — bind a previously approved SCA challenge to a retry.

The wait knob

The 120 upper bound is the hard ceiling enforced via Zod at the input boundary. The practical ceiling is your MCP host's request timeout — Claude Desktop hardcodes ≈ 60 s and Cursor's effective limit is ≈ 30 s, so values above those will surface as host-side timeouts before the wrapper resolves. Use a small wait (e.g. 5-10) when the LLM expects the user to be present and willing to approve immediately. Use wait: false (or wait: 0) for pure two-step flows where the LLM and the user converse out-of-band between the SCA challenge and the retry.

Two-step fallback (out-of-band continuation)

When polling does not resolve, the SCA-pending response carries:

• A user-facing message: "SCA required. The user must approve this operation on their Qonto mobile app."
• A Session token: <token> line (token validity: 15 minutes from issuance).
• Step-by-step instructions to continue.

The LLM (or the user) can then:

1. Poll session status with the sca_session_show tool, passing the captured token. It returns waiting, allow, or deny.
2. Retry the original tool once the status is allow, passing the same parameters plus sca_session_token: "<token>". The wrapper invokes the operation exactly once with the token bound — no second poll happens.

PSD2 dynamic linking. The SCA session token is bound to the original request parameters (amount, payee). Reusing a token against a different operation is rejected by Qonto. Reissue an SCA challenge by calling the original tool again whenever the parameters need to change.

Caller-supplied retry (sca_session_token)

When sca_session_token is set on a wrapped write tool, the wrapper:

• Invokes the operation exactly once.
• Skips polling entirely.
• Forwards the token via the X-Qonto-Sca-Session-Token header.

This is the path used by step (2) of the two-step fallback. It is also useful when the LLM client implements its own polling cadence and only needs the wrapper to retry with an already-captured approval.

Sandbox testing

Sandbox accounts cannot enroll a real paired device, so SCA challenges in sandbox use a mock flow. After receiving a pending response, simulate the user's decision with the sca_session_mock_decision tool (sandbox-only — refuses to run when no staging token is configured). See docs/sandbox-testing.md for the full sandbox setup.

Migration note

Earlier QontoCtl builds (pre-@qontoctl/mcp SCA continuation) returned a free-form text response on 428 with no continuation hooks. Callers parsing that response should adopt the structured flow:

The pending response's textual format is stable, so callers that need to extract the token programmatically can match against the Session token: line — but using sca_session_show directly avoids relying on the response prose.

CLI Usage

First command to try when something doesn't work: qontoctl diagnose — a read-only healthcheck across config, credentials, scopes, organization metadata, and host routing.

Commands

Global Options

Configuration

QontoCtl supports two authentication methods:

• API Key — production-only access using your organization slug and secret key. Supports the endpoints listed as "API key ✔" in the Qonto auth table (most reads plus many writes — internal transfers, clients, attachments, …). Cannot be used against the Qonto sandbox.
• OAuth 2.0 — full access including OAuth-only endpoints (cards, teams, webhooks, e-invoicing, payment links, insurance, international transfers, recurring transfers, SCA flows) and the Qonto sandbox via staging-token; see the OAuth App Setup Guide.

Profile Format

All configuration files use the same YAML format:

# API Key authentication
api-key:
    organization-slug: acme-corp-4821
    secret-key: your-secret-key

# OAuth 2.0 authentication (see docs/oauth-setup.md)
oauth:
    client-id: your-client-id
    client-secret: your-client-secret

Resolution Order

The CLI resolves the config file in this order (highest priority first):

1. --config <path> flag
2. QONTOCTL_CONFIG_FILE env var
3. ~/.qontoctl/{name}.yaml (when --profile <name> is given)
4. ~/.qontoctl.yaml (home default)

When --config is supplied alongside QONTOCTL_CONFIG_FILE or --profile and the resolved paths disagree, --config wins and a warning is emitted on stderr so the override is visible.

No current-directory discovery. The CLI does not scan the working directory for .qontoctl.yaml. For repo-local config, use a direnv shim that exports QONTOCTL_CONFIG_FILE="$PWD/.qontoctl.yaml", or pass --config ./.qontoctl.yaml explicitly per invocation.

Per-field overrides apply on top of the loaded file:

• Without --profile: QONTOCTL_* env vars override file values
• With --profile acme: QONTOCTL_ACME_* env vars override file values

For the full reference (precedence rules per entry point, profile semantics, migration from CWD discovery), see docs/configuration.md.

Environment Variables

Environment variables override file values. They carry inputs (static configuration) the tool reads but never writes back; runtime-mutable state (refresh tokens, token expiry, granted scopes) lives in the file only. See the note on QONTOCTL_ACCESS_TOKEN below.

Without --profile:

With --profile <name>, prefix becomes QONTOCTL_{NAME}_ (uppercased, hyphens replaced with underscores). For example, --profile acme reads QONTOCTL_ACME_ORGANIZATION_SLUG.

QONTOCTL_ACCESS_TOKEN semantics: when set, the env-supplied bearer is used for the current invocation only. Proactive token refresh is not attempted, and refreshed tokens are not persisted to disk (mirrors AWS_SESSION_TOKEN). If the token has expired the API surfaces a 401; re-issue the token externally.

QONTOCTL_REFRESH_TOKEN is intentionally not supported. Refresh tokens are runtime-mutable state — every refresh produces a new value the tool must write back somewhere — and env vars carry inputs, not state. Use file-based credentials (~/.qontoctl.yaml or a profile) for OAuth flows that need refresh, or stick with API-key env vars in CI.

Debug Mode

The --verbose and --debug flags enable wire-level logging to stderr:

qontoctl --verbose transaction list   # request/response summaries
qontoctl --debug transaction list     # full headers and response bodies

Security note: --debug logs full API response bodies. Known sensitive fields (IBAN, BIC, balance) are automatically redacted, but responses may still contain other financial data. Do not use --debug in shared environments or pipe debug output to files accessible by others.

Disclaimer

qontoctl is an independent project not affiliated with, endorsed by, or officially connected to Qonto or Qonto SAS.

Qonto is a trademark of Qonto SAS.

License

AGPL-3.0-only

What AGPL means for you

• Using qontoctl as a CLI tool or MCP server does not make your code AGPL-licensed. Running the tool, scripting around it, or connecting it to your applications is normal use — no license obligations arise.
• Using @qontoctl/core as a library (importing it into your code) means your combined work is covered by AGPL-3.0. If you distribute that combined work, you must make its source available under AGPL-compatible terms.
• Modifying and distributing qontoctl itself requires you to share your changes under AGPL-3.0.
• Commercial licensing is available if AGPL does not fit your use case — contact the maintainer.