qontoctl (Alexey Pelykh)

  ](https://www.npmjs.com/package/qontoctl) ](https://www.npmjs.com/package/qontoctl) ](https://github.com/alexey-pelykh/qontoctl) 

CLI和MCP服务器 Qonto API银行业务。

这个项目是由 阿列克谢·佩利赫.

它的作用

QontoCtl允许AI助手（Claude等）通过 模型上下文协议。它可以：

• 组织 --检索组织详细信息和设置
• 账户 --列出、创建、更新、关闭银行账户；下载IBAN证书
• 交易 --列出、搜索、过滤银行交易；管理交易附件
• 银行对账单 --列出、查看和下载银行对账单
• 标签 --管理交易标签和类别
• 会员资格 --查看团队成员、显示当前成员、邀请新成员
• SEPA受益人 --列出、添加、更新、信任/不信任SEPA受益人
• SEPA转账 --列出、创建、取消转账；下载校样；核实收款人
• 内部转账 --在同一组织中的帐户之间创建转账
• 批量转移 --列出并查看批量传输批次
• 定期转账 --列出并查看定期转账
• 终端（POS） --列出Qonto终端并启动终端支付
• 产品 --列出产品目录
• 客户 --列出、创建、更新、删除客户端
• 客户发票 --完整生命周期：创建、更新、完成、发送、标记已付费、取消、上传文件
• 语录 --创建、更新、删除、发送报价
• 贷记通知 --列出并查看贷方票据
• 供应商发票 --列出、查看和批量创建供应商发票
• 请求： --列出组织请求
• 附件 --上传和查看附件
• 电子发票 --检索电子发票设置

先决条件

• Node.js >= 24
• A. Qonto 具有API访问权限的业务帐户

安装

npm install -g qontoctl

或者直接使用npx运行：

npx qontoctl --help

或通过安装 家酿:

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实施 模型上下文协议 （MCP），让AI助手通过自然语言与您的Qonto帐户进行交互。

MCP客户端配置

Claude Desktop

添加到您的Claude Desktop配置(claude_desktop_config.json):

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

Claude Code

claude mcp add qontoctl -- npx qontoctl mcp

Cursor

添加 .cursor/mcp.json 在项目根目录中：

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

Windsurf

添加 ~/.codeium/windsurf/mcp_config.json:

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

将MCP指向非默认配置文件

MCP服务器没有CLI标志。从配置文件加载凭据，而不是 ~/.qontoctl.yaml，set QONTOCTL_CONFIG_FILE 在主人的 env 块：

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

路径在服务器启动时捕获。看 docs/configuration.md 对于完整的分辨率链。

可用的MCP工具

示例提示

配置后，您可以向AI助手询问以下问题：

• “显示我的Qonto账户余额”
• “列出最近超过1000欧元的交易”
• “上个月的卡付款是多少？”
• “显示我组织中的所有团队成员”
• “列出2026年1月的银行对账单”
• “创建本周借记摘要”

SCA继续

一些Qonto写入操作——创建转账、修改卡、批准请求——需要 强客户身份验证（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秒，因此高于这些值的值将在包装器解析之前作为主机端超时出现。使用小 wait （例如。 5-10)当LLM期望用户在场并愿意立即批准时。使用 wait: false （或 wait: 0)for 纯两步流 其中LLM和用户在SCA质询和重试之间进行带外对话。

两步回退（带外继续）

当轮询未解决时，SCA挂起响应将携带：

• 面向用户的消息： "SCA required. The user must approve this operation on their Qonto mobile app."
• A. Session token: 行（代币有效期：发行后15分钟）。
• 分步说明以继续。

LLM（或用户）可以：

1. 轮询会话状态 随着 sca_session_show 工具，传递捕获的令牌。它回来了 waiting, allow，或 deny.
2. 重试原始工具 一旦状态为 allow，通过 _参数_ 加 sca_session_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 continuation）在428上返回了一个没有continuation钩子的自由格式文本响应。解析该响应的调用者应采用结构化流：

待定响应的文本格式是稳定的，因此需要以编程方式提取令牌的调用者可以与 Session token: 线-但使用 sca_session_show 直接避免依赖回复散文。

CLI使用情况

当某些东西不起作用时尝试的第一个命令: qontoctl diagnose --跨配置、凭据、范围、组织元数据和主机路由的只读健康检查。

命令

全局选项

配置

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

• API密钥 --使用您的组织slug和密钥进行仅限生产的访问。支持列为“API密钥”的端点✔“在 Qonto身份验证表 （大多数读取加上许多写入——内部传输、客户端、附件等）。无法用于Qonto沙盒。
• OAuth 2.0 --完全访问权限，包括仅限OAuth的端点（卡、团队、webhooks、电子发票、支付链接、保险、国际转账、定期转账、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

` 旗帜

1. QONTOCTL_CONFIG_FILE env 是
2. ~/.qontoctl/{name}.yaml （当 --profile 已给出）
3. ~/.qontoctl.yaml （主页默认）

当 --config 随附供应 QONTOCTL_CONFIG_FILE 或 --profile 并且解决的路径不一致， --config 获胜后，stderr上会发出警告，因此覆盖是可见的。

未发现当前目录。 CLI不会扫描工作目录 .qontoctl.yaml.对于repo本地配置，请使用 direnv 出口垫片 QONTOCTL_CONFIG_FILE="$PWD/.qontoctl.yaml"，或通过 --config ./.qontoctl.yaml 明确地每次调用。

按字段覆盖 在加载的文件之上应用：

• 没有 --profile: QONTOCTL_* env变量覆盖文件值
• 随着 --profile acme: QONTOCTL_ACME_* env变量覆盖文件值

有关完整的参考（每个入口点的优先级规则、配置文件语义、从CWD发现的迁移），请参阅 docs/configuration.md.

环境变量

环境变量覆盖文件值。他们携带 输入 （静态配置）该工具读取但从不回写；运行时可变状态（刷新令牌、令牌过期、授予范围）仅存在于文件中。请参阅上的注释 QONTOCTL_ACCESS_TOKEN 在......下面

没有 --profile:

随着 --profile ，前缀变为 QONTOCTL_{NAME}_ （大写，连字符替换为下划线）。例如， --profile acme 读取 QONTOCTL_ACME_ORGANIZATION_SLUG.

QONTOCTL_ACCESS_TOKEN 语义学：设置后，env提供的承载仅用于当前调用。不尝试主动令牌刷新，刷新的令牌不会持久化到磁盘（镜像 AWS_SESSION_TOKEN).如果令牌已过期，API将显示 401；在外部重新发行代币。 QONTOCTL_REFRESH_TOKEN 故意不支持。 刷新令牌是运行时可变的状态——每次刷新都会产生一个新值，工具必须将其写回某个地方——环境变量携带输入，而不是状态。使用基于文件的凭据(~/.qontoctl.yaml 或者简档）、或者在CI中坚持使用API-key env vars。

调试模式

这 --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 SAS。

Qonto是Qonto SAS的商标。

许可证

仅限AGPL-3.0

AGPL对你意味着什么

• 将qontoctl用作CLI工具或MCP服务器 不会使您的代码获得AGPL许可。

运行该工具、围绕它编写脚本或将其连接到您的应用程序是正常的 使用——不产生许可义务。

• 使用 @qontoctl/core 作为一个图书馆 （将其导入到代码中）意味着您的组合

AGPL-3.0涵盖了这项工作。如果你分发合并后的作品，你必须使其 源代码符合AGPL兼容条款。

• 修改和分发qontoctl本身 要求您在下共享您的更改

AGPL-3.0。

• 商业许可 如果AGPL不适合您的用例，则可用——请联系

维护人员。