qbo-multicompany-mcp

qbo-multicompany-mcp

一个只读的 MCP 服务，通过 stdio 向一个 AI 会话提供多个 QuickBooks Online 公司文件。每次调用 QuickBooks 时，都会通过显式的 entity 键指定公司。没有默认公司，也不会按公司名称匹配。

非官方项目。与 Intuit 无关联，也未获其认可。每位用户都需自行注册 Intuit 应用，并自行回答 Intuit 的问题。

适用对象

• 你负责运营或记账的 QuickBooks 公司不止一家，希望助手能跨公司读取数据而不混淆：月末结账、对比公司、追踪交易、核对供应商付款。
• 你为 AI Agent 构建工具，希望参考一个围绕模型实际使用方式设计的 MCP 服务实例。

还有其他 QuickBooks MCP 服务，其中一些来自 Intuit，有些支持多家公司或可以写入账簿。请根据自身需求进行比较。此服务绝不会写入数据。

AI client  -- stdio -->  qbo-multicompany-mcp  -- GET, checked before send -->  QuickBooks Online
                              |
                              +-- entities.yaml        your companies, by key
                              +-- encrypted store      one token chain per company

沙盒环境快速入门

你需要 Python 3.11+、uv，以及一个已将 http://localhost:8765/callback 注册为开发重定向 URI 的 Intuit 开发者应用。

git clone https://github.com/dkaleganov/qbo-multicompany-mcp.git

cd qbo-multicompany-mcp && uv sync --frozen && cp entities.example.yaml entities.yaml && cp .env.example .env && chmod 600 .env entities.yaml

将应用的 Client ID 和 Client Secret 填入 .env，并将沙盒公司填入 entities.yaml。然后创建存储密钥，并在浏览器中连接每家公司：

uv run qbo-multicompany-mcp-auth --env-file .env --entities entities.yaml init-key

uv run qbo-multicompany-mcp-auth --env-file .env --entities entities.yaml connect acme_main

首次连接通常会提示名称不匹配：输入 y，并将打印出的 display_name 复制到 entities.yaml。然后使用绝对路径将服务添加到客户端。--scope user 会让你账户中的每个 Claude Code 会话都能使用此服务，因此你可以在仓库目录之外运行这些会话：

claude mcp add --scope user qbo -- "<repo>/.venv/bin/qbo-multicompany-mcp" --env-file "<repo>/.env" --entities "<repo>/entities.yaml"

docs/getting-started.md 介绍了所有步骤，包括 Claude Desktop 和 Codex。生产环境还需要更多配置：docs/production.md。

从 PyPI 安装，无需克隆

uvx 会运行已发布的软件包。将 .env.example 保存为 .env，将 entities.example.yaml 保存为私人文件夹中的 entities.yaml，对两者执行 chmod 600 ，并按上述说明填写。以下命令中的 <dir> 表示该文件夹的绝对路径：

uvx --from [email protected] qbo-multicompany-mcp-auth --env-file "<dir>/.env" --entities "<dir>/entities.yaml" init-key

uvx --from [email protected] qbo-multicompany-mcp-auth --env-file "<dir>/.env" --entities "<dir>/entities.yaml" connect acme_main

claude mcp add --scope user qbo -- uvx [email protected] --env-file "<dir>/.env" --entities "<dir>/entities.yaml"

工具

默认提供十八个，另有一个需选择启用。docs/tools.md 列出了所有参数，并提供了“选择工具”表格。

工具	返回内容
list_entities	已配置的公司、身份验证状态和令牌时效性。不发送请求
server_info	构建版本、环境、只读状态、存储保护状态。不发送请求
get_company_info	公司资料、设置和推导出的功能
list_accounts	含余额的会计科目表
list_vendors	供应商、1099 标记，以及是否存有税务 ID；绝不返回税务 ID
list_customers	含余额的客户信息，不包含税务 ID、备注或联系信息字段
list_reference_data	类别、部门、项目、条款、付款方式、税码、税率
list_transactions	最长六个月时间范围内的交易
get_transaction	一笔交易及其明细
run_query	一条经解析的 SELECT，根据其解析树重建后通过 GET 发送
list_changes	30 天内列表对象（例如供应商和账户）的变更和删除记录，不含交易
summarize_vendor_payments	按日历年汇总的各供应商候选总额
report_profit_and_loss	按类别列出的收入和支出
report_balance_sheet	截至指定日期的余额
report_general_ledger	按账户列出的记账记录
report_aging	按账龄区间列出的未结应付款或应收款
run_report	其他 21 种已记录的报表
list_attachments	附件元数据，绝不提供链接
get_attachment（选择启用）	文件；仅在使用 --allow-documents 并固定存储主机时提供

为什么它适合与 AI Agent 配合使用

模型可能会调用错误的公司、相信空结果，或用错误的值重试。本服务就是围绕这些情况构建的。

• 每次调用都明确指定公司。 不设默认公司，模型每次都必须指定公司，因此选错时会显示在对话记录中。list_entities 会提供键，且每个进程首次使用时都会通过守卫检查公司的名称。
• 结果会标明所属公司和时间。 QuickBooks 返回的每个答案都会附带实体、环境、realm id（Intuit 的 Company ID）的末四位数字，以及获取时间，因此模型可以说明某个数字来自哪个文件。
• 统一的列表字段。 每个遍历 QuickBooks 分页的列表都会返回 count、rows、truncated、duplicates_dropped 和 pages_walked，让模型只需学习一次结果结构。
• 部分报告会先说明这一点。 单元格或行出现问题时，结果会标记为部分结果，模型读取的文本也会以 PARTIAL RESULT 开头。空报告绝不会据此认定没有数据；list_transactions 在筛选请求返回零行时，会先取消筛选重新检查，再报告“无结果”。
• 拒绝时会说明如何修正，且绝不回显任何值。 拒绝信息会指出参数和原因，通常会在发送任何请求之前给出；你发送的任何文本、ID、日期或数字都不会出现在返回内容中。它可能会提及已配置的实体键，或本服务自身的选项值。有项测试会将带标记的值传入每个工具的每个参数，并确认没有任何拒绝信息会重复这些值。
• 公司文本会标记为不可信。 名称、备注和报告单元格可能包含任何内容。每个会返回这些内容的工具都会在说明中指出，这些内容是提供给模型的不可信输入，且数据可能会传送给其服务提供方。
• 登录由用户本人完成。 用户需在终端和浏览器中完成授权；密钥来自环境变量；没有任何工具会接收或返回密钥或授权码。以你的身份运行的任何程序都可以从任意文件夹读取未加密的 .env 和令牌存储的密钥。如 SECURITY.md 所述，将 AI 会话放在仓库文件夹之外，可避免 .env 和 entities.yaml 出现在 Agent 的工作文件夹中；但拥有 shell 访问权限的 Agent 仍然可以访问这两个文件及密钥。
• 说明会引导选择合适的工具。 每个工具的说明都会指出何时有更合适的工具；docs/tools.md 中的“选择工具”表格则为用户介绍了所有功能。

只读模式及其执行方式

Intuit 不提供只读会计作用域：同一个作用域同时涵盖读取和写入。因此，只读模式由这段代码实现。每个请求都会在发送前立即作为完整构建的 httpx.Request 接受检查；会计请求只能对确切绑定的公司使用允许列表中的路径发送 GET 请求。OAuth 调用只会发送到 Intuit 的固定端点；选择启用的附件下载只会发送到你指定的主机；其他所有请求都会被拒绝。docs/design.md 介绍了相关策略，以及遍历、报告和令牌存储的行为。

验证方式

• 测试。 运行 uv sync --frozen --extra dev，然后运行 uv run pytest -q：2,805 项通过，4 项跳过，无需凭据或网络。此统计需要 git 2.32 或更高版本，并且 gitleaks 位于 PATH 中；没有 gitleaks 时还会多跳过 25 项。
• 变异测试门禁。 测试套件通过并不能证明安全行为受到了保护，因此 scripts/mutation_gate.py 包含 480 个条目，每个条目都会删除一项内容，并要求对应测试失败。它自身也有控制措施，因此不会因什么都没测试而悄然通过。
• 泄漏检查。 为 Intuit 凭据定制的 gitleaks 规则，每条规则都已通过金丝雀证明能够触发；另外还有用于检查形似标识符值的 scripts/scrub_check.py。
• 实时运行。 每个工具都已在沙盒中通过 stdio 运行：本次发布中的默认工具，以及预发布版本中的 get_attachment。除 run_report 下的 TaxSummary 外，每个默认工具都已在 2026-09-28 使用预发布版本在生产环境中以只读方式运行；TaxSummary 从未返回过行。实时运行的发现记录在 docs/api-findings.md 中。

CHANGELOG.md 将已通过实时运行验证的内容与仅在测试数据上运行过的内容分开记录。

示例提示词

你能看到哪些公司？每家公司是否都已连接？

对比 acme_main 和 acme_ops 本财年迄今与上一财年的损益。说明每个数字的来源。

显示 acme_ops 截至上一季度末的资产负债表，然后列出变动超过 10% 的账户背后的日记账分录。

acme_ops 中哪些供应商带有 1099 标记？

列出 2025 年 acme_main 的候选供应商付款，并说明哪些需要审核。

已知限制

• 仅支持只读操作和 QuickBooks Online。 不支持写入，也不支持 QuickBooks Desktop。
• 交易类型有专用工具。 对于交易类型，run_query 会回答 COUNT(*)，并拒绝 SELECT *；list_changes 也会拒绝这些查询。请使用 list_transactions 和 get_transaction。
• 筛选条件的验证方式各不相同。 未知参数名会被上游丢弃；无效枚举值会返回 400；不匹配任何内容的 ID 或文本会返回空的 200。此服务会分别处理这些情况，详见 docs/design.md。
• 供应商付款总额仅为候选值。 这些数据用于与银行分类账交叉核对，并非报税分类器，而且尚未与分类账逐笔人工核对。
• 沙盒不等同于生产环境。 在沙盒中确认的值，在生产环境中的公司上可能并不成立。
• 部分列尚未观测到。 文档中列出了类别、部门和货币报表列，但实时响应中尚未出现这些列。
• get_attachment 仅在沙盒中得到验证。 尚未观测到生产环境的存储主机；主机检查是预先检查，不会绑定到实际连接的地址。
• 遍历并非快照。 即使完整遍历，也可能跨越编辑操作；结果会标记为 non_snapshot。
• 速率限制和配额由 Intuit 管理。 此服务会遵守两种已记录的时间窗口，不会发送无法计数的调用，并会报告 429，而不是等待限流结束。
• uv.lock 在发布时固定。 它会锁定服务及其测试安装的每个软件包，因此请按自己的计划运行 uv lock --upgrade。构建后端 hatchling 不包含在其中：uv 会在构建软件包时解析它。

支持

已在 macOS 上测试。Windows 不受支持：存储依赖 POSIX 文件锁。Linux 在设置 QBO_TOKEN_KEY_SOURCE=env 后应该可以运行，但尚未经过测试。这是一个处于 Alpha 阶段、在此版本冻结的项目，维护以尽力而为为原则：欢迎提交 Bug 报告，安全问题请通过 SECURITY.md 报告。

许可证

MIT。请参阅 LICENSE。