QuickBooks Online

QuickBooks Online MCP 服务

面向 QuickBooks Online Accounting API 的 Model Context Protocol（MCP）服务。为 Claude 和其他兼容 MCP 的客户端提供 130 多个工具，覆盖 22 个 QBO 实体和 10 份财务报表。

功能

• 交互式发票卡片（MCP Apps，SEP-1865）：在 MCP Apps 宿主（Claude Desktop/web）中，qbo_invoices_get 会呈现为只读交互式卡片，显示客户、状态、日期、明细项和总额。默认使用中性样式，可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量来添加品牌样式。非 App 宿主会看到相同的 JSON 负载（另含 _card 字段）。

一键部署

**关于注册表身份验证的说明：**此服务仅依赖公开的 npm 包，因此 Cloudflare 和 DigitalOcean 云构建器会匿名安装其依赖项，一键部署无需令牌。（如果未来版本添加了私有的 @wyre-ai/* 依赖项，你需要提供具有 read:packages 权限的 GitHub PAT 作为构建变量：Cloudflare Workers 使用 NODE_AUTH_TOKEN，DigitalOcean 使用构建时的 GITHUB_TOKEN 密钥。）

**安装已发布的包：**已发布的包托管在 GitHub Packages npm 注册表中，每次安装都需要身份验证（包括公开包）。如需安装，请使用具有 read:packages 权限的 GitHub PAT 对 npm 进行身份验证，以访问 npm.pkg.github.com：

export NODE_AUTH_TOKEN=$(gh auth token)
npm install @wyre-ai/qbo-mcp

快速开始

前提条件

• Node.js >= 20
• QuickBooks Online OAuth2 应用凭据（需要 Intuit 开发者账户）

安装和构建

npm install
npm run build

运行（stdio 模式）

QBO_ACCESS_TOKEN=your-access-token QBO_REALM_ID=your-realm-id npm start

运行（HTTP 模式）

设置 CONDUIT_S2S_SECRET 后，HTTP 才会启动。监听器默认使用 127.0.0.1:8080。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  MCP_TRANSPORT=http \
  QBO_ACCESS_TOKEN=your-access-token \
  QBO_REALM_ID=your-realm-id \
  npm start

不设置密钥的本地 HTTP 仅适用于开发环境。它仅绑定到 127.0.0.1，并会记录一条警告。非环回地址的 MCP_HTTP_HOST 会被忽略，并记录相应日志：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 \
  QBO_ACCESS_TOKEN=your-access-token \
  QBO_REALM_ID=your-realm-id \
  npm start

Docker

镜像会在容器内的 0.0.0.0（MCP_HTTP_HOST）上监听，且默认使用 AUTH_MODE=gateway。请将端口发布到环回地址，并传入真实的 S2S 密钥。在网关模式下，每个请求都会通过 X-Qbo-Access-Token 和 X-Qbo-Realm-Id 传入访问令牌和 realm ID；不会从环境变量中读取这些值。

# Generate the secret first: openssl rand -hex 32
docker build -t qbo-mcp .
docker run \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  qbo-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 将拒绝启动；默认将 AUTH_MODE 设为 gateway，不会注入 QBO_ACCESS_TOKEN 或 QBO_REALM_ID，并会发布 127.0.0.1:8080:8080：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 QBO_ACCESS_TOKEN 和 QBO_REALM_ID：

docker run \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e QBO_ACCESS_TOKEN=your-access-token \
  -e QBO_REALM_ID=your-realm-id \
  -p 127.0.0.1:8080:8080 \
  qbo-mcp

环境变量

变量	必填	默认值	说明
QBO_ACCESS_TOKEN	用于 stdio 和 AUTH_MODE=env	—	QuickBooks Online OAuth2 访问令牌。Compose 网关服务不会加载此变量。
QBO_REALM_ID	用于 stdio 和 AUTH_MODE=env	—	QuickBooks Online 公司（realm）ID。Compose 网关服务不会加载此变量。
QBO_ENV	否	production	API 环境：production 或 sandbox
QBO_CREDENTIALS_FILE	否	—	dotenv 格式文件的路径，每次请求时都会重新读取；文件中的 QBO_ACCESS_TOKEN / QBO_REALM_ID / QBO_ENV 会覆盖环境变量（参见令牌轮换）。网关 Compose 服务不会使用此文件。
MCP_TRANSPORT	否	stdio	传输类型：stdio 或 http
MCP_HTTP_PORT	否	8080	HTTP 服务端口
MCP_HTTP_HOST	否	127.0.0.1	当 MCP_TRANSPORT=http 时的绑定地址。配置了 CONDUIT_S2S_SECRET 时会遵循此值。容器镜像设置为 0.0.0.0。未设置密钥时，MCP_ALLOW_INSECURE_DEV=1 仅绑定到 127.0.0.1。
AUTH_MODE	否	env（镜像和 Compose：gateway）	gateway 或 env。网关模式要求每个 /mcp 请求都携带 X-Qbo-Access-Token 和 X-Qbo-Realm-Id，且绝不会回退到 QBO_*。只有通过 S2S 身份验证后，env 模式才会使用这些环境变量。
CONDUIT_S2S_SECRET	HTTP 必填	—	服务间密钥。使用 openssl rand -hex 32 生成。如果此值为空或为已知占位值（changeme、your-s2s-secret、secret、placeholder 及类似公开示例），HTTP 服务会记录错误并以非零状态码退出。未设置此值时，Compose 不会启动。切勿提交真实值。此值绝不会被记录。
MCP_ALLOW_INSECURE_DEV	否	—	仅用于本地开发时，设置为恰好 1，即可在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制要求 X-Gateway-S2S，并将监听地址强制设为 127.0.0.1，即使 MCP_HTTP_HOST 设置为范围更广的地址。已知占位密钥仍会被拒绝。
MCP_BRAND_NAME	否	—	显示在 MCP Apps 发票卡片上的品牌名称（未设置时卡片使用中性样式）
MCP_BRAND_LOGO_URL	否	—	发票卡片的 Logo URL
MCP_BRAND_PRIMARY_COLOR	否	#2563eb	发票卡片的主色
MCP_BRAND_ACCENT_COLOR	否	#e5e7eb	发票卡片的强调色
MCP_BRAND_BG	否	#ffffff	发票卡片的背景色
MCP_BRAND_TEXT	否	#333333	发票卡片的文字颜色

身份验证

此服务端不处理 OAuth 流程，而是使用预先获取的访问令牌。共有两种模式：

env 模式（进程默认模式）。 令牌来自 QBO_ACCESS_TOKEN（如果设置了 QBO_CREDENTIALS_FILE 指定的文件，则优先使用该文件）。单租户。Docker 镜像和 Compose 文件默认使用网关模式。

网关模式。 令牌来自每个请求的 HTTP 标头，并通过 AsyncLocalStorage 隔离，确保并发请求不会共享凭据。设置 AUTH_MODE=gateway，并发送 X-Qbo-Access-Token 和 X-Qbo-Realm-Id。缺少其中任一标头的请求都会收到 HTTP 401，且不会回退到进程环境中的 QBO_ACCESS_TOKEN / QBO_REALM_ID。

标头	必填	说明
X-Qbo-Access-Token	是	OAuth2 访问令牌
X-Qbo-Realm-Id	是	公司（realm）ID
X-Qbo-Environment	否	production 或 sandbox（默认值为 production）

/health 无需身份验证，且不会读取凭据。stdio 传输不会使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。验证逻辑位于 src/s2s-verify.ts 的 verifyS2sHeader 中：标头值的格式为 t=<unix seconds>,v1=<hex>，其中十六进制值是以 CONDUIT_S2S_SECRET 为密钥、对字面字符串 t=<unix seconds> 计算的 HMAC-SHA256（64 个小写十六进制字符）。时间戳与服务器时钟的偏差必须在 300 秒以内。若标头缺失或无效，服务器会在读取供应商凭据前返回 HTTP 401。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-Qbo-Access-Token: $QBO_ACCESS_TOKEN" \
  -H "X-Qbo-Realm-Id: $QBO_REALM_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

在 AUTH_MODE=gateway 下，请求的凭据只能来自这些 X-Qbo-* 标头。在 AUTH_MODE=env 下，如果标头缺失，签名请求会使用环境变量中的 QBO_ACCESS_TOKEN 和 QBO_REALM_ID。

当 QBO 拒绝访问令牌时，服务器会返回 MCP 错误，其文本以字面前缀 QBO_UNAUTHORIZED: 开头。预期的约定是，网关检测到此前缀后刷新 OAuth 令牌，并重试请求。

令牌轮换（env 模式）

QBO 访问令牌约 60 分钟后过期，因此 env 模式部署通常会通过 cron 作业轮换令牌。Docker env_file 中轮换后的令牌不会传入正在运行的容器：Docker 只会在容器创建时注入 env_file，因此 docker restart 会保留旧环境变量；刷新循环也会悄然变成空操作，直到调用开始因 QBO_UNAUTHORIZED / Token revoked 而失败（#63）。

设置 QBO_CREDENTIALS_FILE 即可完全跳过环境变量重新注入。服务器会在每次请求时重新读取该文件，因此轮换会立即生效，无需重启或重新创建容器：

# Single-tenant HTTP. This is separate from the gateway Compose service,
# which does not set QBO_* credentials.
services:
  qbo-mcp:
    image: ghcr.io/wyre-ai/qbo-mcp
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      MCP_TRANSPORT: http
      AUTH_MODE: env
      MCP_HTTP_HOST: 0.0.0.0
      CONDUIT_S2S_SECRET: ${CONDUIT_S2S_SECRET:?set CONDUIT_S2S_SECRET}
      QBO_CREDENTIALS_FILE: /secrets/qbo.env
    volumes:
      - ./secrets:/secrets:ro   # mount the DIRECTORY, not the file

之后，刷新作业只需重写 ./secrets/qbo.env（dotenv 格式：QBO_ACCESS_TOKEN=...，可选的 QBO_REALM_ID=... 和 QBO_ENV=...）即可完成——从脚本中删除 docker restart。请挂载所在目录，而不要直接挂载文件：sed -i 等工具会替换文件的 inode，而单文件绑定挂载会继续指向旧文件。如果文件缺失或不可读，工具调用会明确报错，而不会悄然回退到过期的环境变量令牌。

如果你更希望继续使用普通的 env_file 注入，轮换脚本必须重新创建容器——docker compose up -d --force-recreate；仅执行 docker restart 永远不够。

沙盒测试

设置 QBO_ENV=sandbox（env 模式）或 X-Qbo-Environment: sandbox（gateway 模式），即可将请求发送至 Intuit 的沙盒 API https://sandbox-quickbooks.api.intuit.com，而不是生产环境。无法识别的值会明确报错（不会静默回退到生产环境）。

可用工具

工具按领域分类。调用 qbo_navigate 并传入领域名称（例如 customers、vendors、bills），即可发现该领域的工具。所有工具始终都可调用——导航仅用于发现工具，并非调用前提。

实体（基于配置，涵盖 22 个实体的 122 个工具）

每个实体均提供 list、get、create、update、void、search 中的部分操作。交易类实体的 list 操作支持按 startDate/endDate 筛选。更新采用稀疏更新方式，并要求提供先前通过 get 获取的当前 SyncToken。只有 QBO Accounting API 支持作废的实体才提供 void 操作（Invoice 使用 ?operation=void；Payment 使用 ?operation=update&include=void）。Customer 不支持作废或删除——更新时将 Active 设为 false 即可停用。

销售工作流

• qbo_customers_* — list、get、create、update、search（不支持作废；通过 Active: false 停用）
• qbo_invoices_* — list（支持按 Paid/Unpaid/Overdue 状态筛选）、get、create、update、void、send
• qbo_estimates_* — list、get、create、update
• qbo_sales_receipts_* — list、get、create、update
• qbo_credit_memos_* — list、get、create、update
• qbo_refund_receipts_* — list、get、create、update
• qbo_payments_* — list、get、create、update、void

采购工作流

• qbo_vendors_* — list、get、create、update、search
• qbo_bills_* — list、get、create、update、search
• qbo_bill_payments_* — list、get、create、update
• qbo_vendor_credits_* — list、get、create、update
• qbo_purchases_* — list、get、create、update（销售点支出）
• qbo_purchase_orders_* — list、get、create、update

银行与资金流转

• qbo_deposits_* — list、get、create、update
• qbo_transfers_* — list、get、create、update
• qbo_journal_entries_* — list、get、create、update（借贷平衡）

产品与账户

• qbo_items_* — list、get、create、update、search（产品与服务）
• qbo_accounts_* — list、get、create、update、search（会计科目表）

分类与条款

• qbo_classes_* — list、get、create、update、search
• qbo_departments_* — list、get、create、update、search
• qbo_terms_* — list、get、create、update、search（Net 30 等）
• qbo_payment_methods_* — list、get、create、update、search

税务与公司

• qbo_tax_codes_* — list、get、search（只读）
• qbo_tax_rates_* — list、get、search（只读）
• qbo_company_info_* — list、get（只读单例）

人员与时间

• qbo_employees_* — list、get、create、update、search
• qbo_time_activities_* — list、get、create、update（可计费时间）

附件

• qbo_attachables_* — list、get、create、update（仅元数据；文件上传使用单独的 QBO 端点）

报告（10 个工具）

• qbo_reports_profit_and_loss
• qbo_reports_balance_sheet
• qbo_reports_cash_flow
• qbo_reports_trial_balance
• qbo_reports_general_ledger
• qbo_reports_aged_receivables
• qbo_reports_aged_payables
• qbo_reports_customer_sales
• qbo_reports_customer_balance
• qbo_reports_vendor_expenses

旧版支出工具（向后兼容）

qbo_expenses_list_purchases、qbo_expenses_get_purchase、qbo_expenses_list_bills、qbo_expenses_get_bill 仍可使用。新开发应使用专用的 qbo_purchases_* 和 qbo_bills_* 工具系列，它们额外支持 create/update/search。

测试

npm test                   # unit suite — fast, no credentials needed
npm run test:integration   # hits a real QBO sandbox; skipped without creds

集成测试套件会针对 Intuit 的沙盒 API，对每个实体类别（客户、供应商、账户、商品、日记账分录、公司信息）各调用一个只读工具。仅当环境中同时存在 QBO_SANDBOX_ACCESS_TOKEN 和 QBO_SANDBOX_REALM_ID 时才会运行。CI 会从对应的仓库机密中注入这些值；若缺少这些值，则会跳过该任务并发出明确提示，因此 dependabot/fork PR 不会因此失败。

许可证

Apache-2.0