qontoctl

Qonto 銀行 API 用の CLI と MCP サーバーです。

このプロジェクトは Alexey Pelykh によって提供されています。

非公式プロジェクトです。 QontoCtl は独立したプロジェクトであり、Qonto との提携、承認、支援を受けていません。詳しくは免責事項をご覧ください。

できること

QontoCtl を使うと、AI アシスタント（Claude など）が Model Context Protocol を通じて Qonto を操作できます。次のことができます。

• 組織 — 組織の詳細と設定を取得
• 口座 — 銀行口座の一覧表示、作成、更新、閉鎖、IBAN 証明書のダウンロード
• 取引 — 銀行取引の一覧表示、検索、絞り込み、取引の添付ファイルの管理
• 銀行明細書 — 銀行明細書の一覧表示、閲覧、ダウンロード
• ラベル — 取引のラベルとカテゴリを管理
• メンバーシップ — チームメンバーの閲覧、現在のメンバーシップの表示、新しいメンバーの招待
• SEPA 受取人 — SEPA 受取人の一覧表示、追加、更新、信頼設定と信頼解除
• SEPA 振込 — 振込の一覧表示、作成、キャンセル、証明書のダウンロード、受取人の確認
• 内部振込 — 同じ組織内の口座間で振込を作成
• 一括振込 — SEPA 一括振込の一覧表示、閲覧、作成
• 定期振込 — 定期振込の一覧表示、閲覧、作成、キャンセル
• 国際振込（SWIFT） — SWIFT 振込の作成と国際受取人の管理
• カード — カードの一覧表示、作成、更新、ロックとロック解除、紛失・盗難の報告、破棄
• チーム — チームの一覧表示と作成
• Webhook — Webhook サブスクリプションの作成と管理
• 決済リンク — Stripe を利用した決済リンクの作成、無効化、管理
• 保険 — 保険契約の表示、作成、更新、書類の管理
• 端末（POS） — Qonto 端末の一覧表示と端末決済の開始
• 商品 — 商品カタログの一覧表示
• クライアント — クライアントの一覧表示、作成、更新、削除
• クライアント請求書 — ライフサイクル全体：作成、更新、確定、送信、支払済みとして記録、キャンセル、ファイルのアップロード
• 見積書 — 見積書の作成、更新、削除、送信
• クレジットノート — クレジットノートの一覧表示と閲覧
• 仕入先請求書 — 仕入先請求書の一覧表示、閲覧、一括作成
• リクエスト — 組織のリクエストの一覧表示
• 添付ファイル — 添付ファイルのアップロードと閲覧
• 電子請求書 — 電子請求書の設定を取得

QontoCtl と Qonto 公式 MCP

QontoCtl は独立した非公式プロジェクトであり、Qonto との提携や Qonto による推奨は受けていません。

Qonto は独自の公式 MCP サーバーを提供しています。ホスト型で、すべてのプランで無料で利用でき、Claude、ChatGPT、Cursor などからタップひとつでインストールできます。財務について「残高を表示して」「先月の支出をグラフにして」「請求書の下書きを作成して」などと_話しかけたい_場合、優れた、よくできた選択肢です。

QontoCtl は別の用途、つまり Qonto と会話するだけでなく、Qonto を自動化するために作られています。

公式 MCP は、ユーザーとしてログインして利用するホスト型アシスタントです。QontoCtl は、CLI、MCP サーバー、ライブラリを備えたローカルのオープンソースツールキットです。自身の認証情報を使って自分のマシン上で実行でき、ヘッドレスのサービスアカウントとしても利用できます。

_{比較は、2026 年 7 月時点の Qonto 公開 MCP ドキュメントに基づいています。}

_{* 信頼されていない受取人への振込には、当然ながら Strong Customer Authentication による承認が引き続き必要です。QontoCtl は SCA の続行処理を行うため、信頼済みの受取人への振込や自身の口座間の振込といったスクリプト化されたフローは、端末で人が操作しなくても完了します。}

QontoCtl は、名前付きプロファイルを使って、1 つのセットアップから複数の Qonto 組織にも対応します。会計士、持株会社、複数の法人の帳簿を管理する人に便利です。

公式 MCP は Qonto と会話します。QontoCtl は Qonto を自動化します。 多くの人は両方を使うでしょう。チャットウィンドウでは公式 MCP、パイプラインでは QontoCtl を利用できます。

前提条件

• Node.js >= 24
• API アクセスが可能な Qonto ビジネスアカウント

インストール

npm install -g qontoctl

または npx で直接実行します。

npx qontoctl --help

または Homebrew でインストールします。

brew install qontoctl/tap/qontoctl

クイックスタート

# 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 統合

QontoCtl は Model Context Protocol（MCP）を実装しており、AI アシスタントが自然言語を通じて Qonto アカウントを操作できます。

MCP クライアントの設定

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

claude mcp add qontoctl -- npx qontoctl mcp

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

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

MCP の設定ファイルにデフォルト以外のファイルを指定する

MCP サーバーには CLI フラグがありません。~/.qontoctl.yaml 以外の設定ファイルから認証情報を読み込むには、ホストの env ブロックで QONTOCTL_CONFIG_FILE を設定します。

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

パスはサーバーの起動時に取得されます。解決順序の詳細については、docs/configuration.md を参照してください。

利用可能な MCP ツール

プロンプトの例

設定が完了したら、AI アシスタントに次のようなことを尋ねられます。

• 「Qonto アカウントの残高を表示して」
• 「1,000 EUR を超える最近の取引を一覧表示して」
• 「先月のカード支払いは？」
• 「組織内のチームメンバーをすべて表示して」
• 「2026 年 1 月の銀行取引明細を一覧表示して」
• 「今週の引き落としの概要を作成して」

SCA の継続

送金の作成、カードの変更、リクエストの承認など、Qonto の一部の書き込み操作では、**強力な顧客認証（SCA）**が必要です。実行前に、ユーザーが Qonto モバイルアプリでリクエストを承認する必要があります。QontoCtl は、SCA が必要なすべての MCP 書き込みツールを継続フローでラップするため、LLM クライアント側でポーリングを再実装する必要はありません。

ラップされた書き込みツールの動作

transfer_create、card_create、beneficiary_trust、request_approve などの SCA が必要なツールで 428 SCA チャレンジが発生すると、ラッパーは SCA セッションをインラインでポーリングします。ポーリング期間内にユーザーが承認すると、ツールは操作の成功結果を透過的に返します。LLM が SCA の往復処理を認識することはありません。ポーリングがタイムアウトした場合（またはポーリングが無効の場合）、ツールはセッショントークンと継続手順を含む、構造化された SCA 保留中レスポンスを返します。

ラップされた各ツールでは、このフローに使用する次の 2 つの任意の入力フィールドが公開されます。

• wait — 保留中レスポンスに切り替えるまで、インラインでポーリングする最大秒数です。
• sca_session_token — 以前に承認された SCA チャレンジを再試行に関連付けます。

wait の設定

120 という上限は、入力境界で Zod によって適用されるハード上限です。実際の上限は、MCP ホストのリクエストタイムアウトです。Claude Desktop では約 60 秒、Cursor では実質約 30 秒に固定されているため、これらを超える値を指定すると、ラッパーが処理を完了する前にホスト側でタイムアウトが発生します。LLM がユーザーがその場ですぐに承認することを想定している場合は、小さな wait（例：5～10）を使用してください。SCA チャレンジと再試行の間に LLM とユーザーが別の経路でやり取りする 純粋な 2 段階フローでは、wait: false（または wait: 0）を使用してください。

2 段階のフォールバック（別経路での継続）

ポーリングで解決しなかった場合、SCA 保留中レスポンスには次の情報が含まれます。

• ユーザー向けメッセージ："SCA required. The user must approve this operation on their Qonto mobile app."
• Session token: <token> という行（トークンの有効期限：発行から 15 分）。
• 継続するための手順。

その後、LLM（またはユーザー）は次の操作を行えます。

1. sca_session_show ツールに取得したトークンを渡して、セッションの状態をポーリングします。waiting、allow、deny のいずれかが返されます。
2. 状態が allow になったら、sca_session_token: "<token>" と 同じパラメーター を渡して、元のツールを再試行します。ラッパーはトークンを関連付けて操作を 1 回だけ実行し、2 回目のポーリングは行いません。

PSD2 の動的リンク。 SCA セッショントークンは、元の リクエストパラメーター（金額、受取人）に関連付けられます。別の操作にトークンを再利用すると、Qonto によって拒否されます。パラメーターを変更する必要がある場合は、元のツールを再度呼び出して SCA チャレンジを再発行してください。

呼び出し側が指定する再試行（sca_session_token）

ラップされた書き込みツールで sca_session_token が設定されている場合、ラッパーは次のように動作します。

• 操作を1回だけ実行します。
• ポーリングを完全にスキップします。
• トークンを X-Qonto-Sca-Session-Token ヘッダーで転送します。

これは、2段階フォールバックのステップ（2）で使用する方法です。また、LLM クライアントが独自のポーリング間隔を実装しており、すでに取得した承認を使ってラッパーに再試行させるだけでよい場合にも便利です。

サンドボックスでのテスト

サンドボックスアカウントでは実際にペアリングされたデバイスを登録できないため、サンドボックスの SCA チャレンジでは mock フローを使用します。保留中のレスポンスを受け取ったら、sca_session_mock_decision ツールを使ってユーザーの判断をシミュレートします（サンドボックス専用。ステージングトークンが設定されていない場合は実行を拒否します）。サンドボックスのセットアップ全体については、docs/sandbox-testing.md を参照してください。

移行に関する注意

以前の QontoCtl ビルド（SCA 継続機能の @qontoctl/mcp 導入前）では、428 時に継続用フックのない自由形式のテキストレスポンスが返されていました。このレスポンスを解析している呼び出し側は、構造化されたフローに移行してください。

保留中のレスポンスのテキスト形式は安定しているため、トークンをプログラムで抽出する必要がある呼び出し側は、Session token: の行を照合できます。ただし、レスポンスの文章に依存しないよう、sca_session_show を直接使用する方法がおすすめです。

CLI の使い方

うまく動作しない場合に、まず試すコマンド：qontoctl diagnose。設定、認証情報、スコープ、組織メタデータ、ホストルーティングを対象に、読み取り専用のヘルスチェックを実行します。

コマンド

グローバルオプション

設定

QontoCtl は2種類の認証方法に対応しています。

• API Key — 組織のスラッグとシークレットキーを使用して、本番環境のみでアクセスします。Qonto 認証テーブルで「API key ✔」と記載されたエンドポイントに対応しています（読み取りの大半と、多くの書き込み操作 — 内部送金、クライアント、添付ファイルなど）。Qonto サンドボックスでは使用できません。
• OAuth 2.0 — OAuth 専用エンドポイント（カード、チーム、Webhook、電子請求書、決済リンク、保険、国際送金、定期送金、SCA フロー）と、ステージングトークン経由の Qonto サンドボックスを含む、すべての機能にアクセスできます。OAuth アプリ設定ガイドを参照してください。

プロファイル形式

すべての設定ファイルで同じ YAML 形式を使用します。

# 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

解決順序

CLI は次の順序で設定ファイルを解決します（優先度の高い順）。

1. --config <path> フラグ
2. QONTOCTL_CONFIG_FILE 環境変数
3. ~/.qontoctl/{name}.yaml（--profile <name> が指定されている場合）
4. ~/.qontoctl.yaml（ホームディレクトリのデフォルト）

QONTOCTL_CONFIG_FILE または --profile と併せて --config が指定され、解決されたパスが一致しない場合は、--config が優先されます。上書きが分かるよう、stderr に警告が出力されます。

カレントディレクトリからの検索は行いません。 CLI は作業ディレクトリ内の .qontoctl.yaml を検索しません。リポジトリ内の設定には、QONTOCTL_CONFIG_FILE="$PWD/.qontoctl.yaml" をエクスポートする direnv のシムを使うか、呼び出しごとに --config ./.qontoctl.yaml を明示的に渡してください。

フィールドごとの上書きは、読み込まれたファイルの設定に適用されます。

• --profile を指定しない場合：QONTOCTL_* 環境変数でファイルの値を上書きします
• --profile acme を指定する場合：QONTOCTL_ACME_* 環境変数でファイルの値を上書きします

エントリーポイントごとの優先順位ルール、プロファイルの動作、CWD 検索からの移行については、全項目を網羅したリファレンス docs/configuration.md を参照してください。

環境変数

環境変数はファイル内の値より優先されます。環境変数が保持するのは、ツールが読み取るものの書き戻すことのない入力（静的な設定）です。実行時に変更される状態（リフレッシュトークン、有効期限、付与されたスコープ）はファイル内にのみ保存されます。以下の QONTOCTL_ACCESS_TOKEN に関する注記を参照してください。

--profile を指定しない場合：

--profile <name> を指定すると、プレフィックスは QONTOCTL_{NAME}_ になります（大文字に変換し、ハイフンはアンダースコアに置き換えます）。たとえば、--profile acme を指定すると、QONTOCTL_ACME_ORGANIZATION_SLUG が読み込まれます。

QONTOCTL_ACCESS_TOKEN の動作：設定されている場合、環境変数で指定されたベアラートークンは、現在の実行時に限り使用されます。事前のトークン更新は試みられず、更新されたトークンがディスクに保存されることもありません（AWS_SESSION_TOKEN と同様です）。トークンの有効期限が切れている場合、API は 401 を返します。トークンは外部で再発行してください。

QONTOCTL_REFRESH_TOKEN は意図的にサポートされていません。 リフレッシュトークンは実行時に変更される状態です。更新のたびに新しい値が生成され、ツールがどこかに書き戻す必要があるためです。環境変数が保持するのは状態ではなく入力です。リフレッシュが必要な OAuth フローには、ファイルベースの認証情報（~/.qontoctl.yaml またはプロファイル）を使用するか、CI では API キーの環境変数を使用してください。

デバッグモード

--verbose フラグと --debug フラグを指定すると、標準エラー出力にワイヤーレベルのログが出力されます。

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

セキュリティに関する注意： --debug は API レスポンス本文全体を記録します。既知の機密フィールド（IBAN、BIC、残高）は自動的にマスキングされますが、レスポンスにはその他の財務データが含まれる場合があります。共有環境で --debug を使用したり、デバッグ出力を他の人がアクセスできるファイルに書き出したりしないでください。

免責事項

qontoctl は、Qonto と提携、承認、または公式に関係していない独立したプロジェクトです。お使いのマシン上で、お客様自身の認証情報を使用して動作します。

「Qonto」および Qonto のロゴは、Qonto を運営する Olinda SAS の商標です。qontoctl は、連携するサービスを表す目的でのみ名称を使用しています。

ライセンス

AGPL-3.0-only

AGPL が利用者に意味すること

• CLI ツールまたは MCP サーバーとして qontoctl を使用しても、お客様のコードが AGPL ライセンスになることはありません。 ツールの実行、ツールを使ったスクリプトの作成、アプリケーションとの接続は通常の利用であり、ライセンス上の義務は発生しません。
• ライブラリとして @qontoctl/core を使用する場合（コードにインポートする場合）、結合した成果物は AGPL-3.0 の適用対象となります。その結合した成果物を配布する場合、AGPL と互換性のある条件でソースコードを公開する必要があります。
• qontoctl 自体を改変して配布する場合、変更内容を AGPL-3.0 のもとで共有する必要があります。
• AGPL が用途に合わない場合は、商用ライセンスを利用できます。メンテナーにお問い合わせください。