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 提供了自己的官方 MCP 服务——托管式服务，所有套餐均可免费使用，并且可以从 Claude、ChatGPT、Cursor 等产品中一键安装。如果你想通过对话_查询_财务信息，例如“显示我的余额”“绘制上个月的支出图表”或“起草一张发票”，这是一个出色且制作精良的选择。

QontoCtl 则为另一种任务而打造：自动化操作 Qonto，而不只是与它对话。

官方 MCP 是一个托管式助手，你需要以用户身份登录。QontoCtl 是一套本地开源工具包，包含命令行工具、MCP 服务和库，可使用你自己的凭据在自己的计算机上运行，也可作为无头服务账户运行。

_{此比较基于截至 2026 年 7 月的 Qonto 公开 MCP 文档。}

_{* 向不受信任的收款人转账仍需你通过强客户身份验证审批，这是必要的。QontoCtl 会处理 SCA 后续流程，因此脚本化工作流——向受信任的受益人转账，以及在你自己的账户之间转账——无需有人守在终端前即可完成。}

QontoCtl 还支持通过命名配置文件在一个设置中使用多个 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 账户余额”
• “列出金额超过 1000 EUR 的近期交易”
• “上个月有哪些银行卡付款？”
• “显示我所在组织的所有团队成员”
• “列出 2026 年 1 月的银行对账单”
• “汇总本周的借记交易”

SCA 续办

某些 Qonto 写入操作——创建转账、修改银行卡、批准请求——需要 Strong Customer Authentication（SCA）：用户必须先在 Qonto 移动应用中批准请求，操作才会执行。QontoCtl 会为每个受 SCA 限制的 MCP 写入工具封装续办流程，因此 LLM 客户端无需重新实现轮询逻辑。

封装后的写入工具如何运行

当受 SCA 限制的工具（例如 transfer_create、card_create、beneficiary_trust、request_approve）遇到 428 SCA 挑战时，封装器会在内部轮询 SCA 会话。如果用户在轮询时限内批准请求，工具会直接返回操作成功结果，LLM 不会看到 SCA 往返流程。如果轮询超时（或已禁用轮询），工具会返回结构化的 SCA 待处理响应，其中包含会话令牌和后续操作说明。

每个封装后的工具都会提供两个用于此流程的可选输入字段：

• wait — 内部轮询的最长秒数，超时后返回待处理响应。
• sca_session_token — 将先前已批准的 SCA 挑战绑定到重试请求。

wait 参数

120 的上限是通过输入边界上的 Zod 强制执行的硬性上限。实际可用时限取决于 MCP 主机的请求超时设置——Claude Desktop 将其硬编码为约 60 秒，Cursor 的实际限制约为 30 秒，因此超过这些时限的值会在封装器完成处理前触发主机侧超时。如果 LLM 预计用户会在场并立即批准，请使用较小的 wait 值（例如 5–10）。如果需要 纯两步流程，即 LLM 与用户在 SCA 挑战和重试之间通过带外方式交互，请使用 wait: false（或 wait: 0）。

两步回退（带外续办）

轮询未完成时，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>"。封装器会使用已绑定的令牌恰好调用一次操作，不会再次轮询。

PSD2 动态关联。 SCA 会话令牌与 原始 请求参数（金额、收款人）绑定。将令牌用于不同操作会被 Qonto 拒绝。如果需要更改参数，请再次调用原始工具以重新发起 SCA 挑战。

调用方提供的重试（sca_session_token）

在封装的写入工具上设置 sca_session_token 后，封装器会：

• 恰好调用一次操作。
• 完全跳过轮询。
• 通过 X-Qonto-Sca-Session-Token 标头转发令牌。

这是两步回退流程中第 (2) 步使用的路径。如果 LLM 客户端自行实现轮询节奏，只需要封装器使用已捕获的批准进行重试，这种方式也很有用。

沙箱测试

沙箱账户无法注册真实的配对设备，因此沙箱中的 SCA 挑战使用 mock 流程。收到待处理响应后，使用 sca_session_mock_decision 工具模拟用户的决定（仅限沙箱——未配置预发布令牌时会拒绝运行）。完整的沙箱设置请参见 docs/sandbox-testing.md。

迁移说明

早期版本的 QontoCtl（在 @qontoctl/mcp 支持 SCA 续接之前）遇到 428 时会返回自由格式文本响应，且没有续接钩子。解析此响应的调用方应采用结构化流程：

待处理响应的文本格式稳定，因此需要以编程方式提取令牌的调用方可以匹配 Session token: 行——但直接使用 sca_session_show 可避免依赖响应文本。

CLI 用法

遇到问题时首先尝试的命令：qontoctl diagnose——对配置、凭据、作用域、组织元数据和主机路由进行只读健康检查。

命令

全局选项

配置

QontoCtl 支持两种身份验证方式：

• API Key — 仅限生产环境访问，使用组织 slug 和密钥。支持 Qonto 身份验证表中标记为“API key ✔”的端点（大多数读取操作以及许多写入操作——内部转账、客户、附件等）。无法用于 Qonto 沙盒。
• OAuth 2.0 — 完整访问权限，包括仅限 OAuth 的端点（卡片、团队、webhook、电子发票、付款链接、保险、国际转账、定期转账、SCA 流程），并可通过 staging-token 访问 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（主目录默认配置）

当 --config 与 QONTOCTL_CONFIG_FILE 或 --profile 同时提供，且解析出的路径不一致时，以 --config 为准，并在 stderr 中发出警告，以便清楚显示覆盖情况。

不会搜索当前目录。 CLI 不会扫描工作目录中的 .qontoctl.yaml。如需使用仓库本地配置，请使用 direnv shim 导出 QONTOCTL_CONFIG_FILE="$PWD/.qontoctl.yaml"，或在每次调用时显式传入 --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 的语义：设置后，环境变量提供的 bearer 令牌仅用于当前调用。不会尝试主动刷新令牌，也不会将刷新后的令牌持久化到磁盘（与 AWS_SESSION_TOKEN 的行为一致）。如果令牌已过期，API 会返回 401；请在外部重新签发令牌。

有意不支持 QONTOCTL_REFRESH_TOKEN。 刷新令牌属于运行时可变状态——每次刷新都会生成一个新值，工具必须将其写回某处——而环境变量承载的是输入，而非状态。对于需要刷新的 OAuth 流程，请使用基于文件的凭据（~/.qontoctl.yaml 或配置档案）；在 CI 中则可继续使用 API 密钥环境变量。

调试模式

--verbose 和 --debug 标志会将网络级日志输出到 stderr：

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 徽标是 Olinda SAS（运营 Qonto 的公司）的商标；qontoctl 仅使用该名称来描述它所交互的服务。

许可证

AGPL-3.0-only

AGPL 对你的意义

• 将 qontoctl 用作命令行工具或 MCP 服务，不会使你的代码受 AGPL 许可。 运行该工具、围绕它编写脚本，或将其连接到你的应用程序，均属正常 使用——不会产生许可义务。
• 将 @qontoctl/core 用作库（在代码中导入它），意味着你的组合 作品受 AGPL-3.0 许可约束。如果你分发该组合作品，必须以兼容 AGPL 的条款 提供其源代码。
• 修改并分发 qontoctl 本身，要求你依据 AGPL-3.0 分享所做的更改。
• 可申请商业许可，如果 AGPL 不适合你的使用场景，请联系 维护者。