QuickBooks Online MCP Server

QuickBooks Online MCP 服务

适用于 Claude Desktop 和任意 MCP 客户端的 QuickBooks Online MCP 服务，使用 Python 和官方 MCP SDK（FastMCP）编写。它提供 18 个用于发票、客户和付款的工具（创建、读取、更新、删除、列出、搜索），以及只读的公司和应收款资源；通过真正的 OAuth 2.1 授权码 + PKCE 流程实现，并支持自动刷新令牌、遵循 QuickBooks 限流规则的客户端限流，以及能告知 Agent 下一步操作的结构化错误。支持通过 stdio 和 Streamable HTTP 运行。

相关项目：HubSpot CRM MCP 服务 · MCP 审计网关 · 生产级 MCP 实际所需

架构

flowchart LR
    Agent["MCP client<br/>(Claude Desktop / HTTP)"]
    subgraph Server["mcp-quickbooks (FastMCP)"]
        Tools["18 tools<br/>invoices · customers · payments"]
        Resources["resources<br/>company · receivables · customers"]
        Client["QBOClient<br/>retry · backoff · error mapping"]
        RL["RateLimiter<br/>per-second + per-minute buckets"]
        Auth["AuthManager<br/>OAuth 2.1 + PKCE · token refresh"]
        Store[("token store<br/>.qbo_tokens.json")]
    end
    QBO["Intuit QuickBooks Online API<br/>/v3/company/{realmId}"]

    Agent <-->|stdio / streamable-http| Tools
    Agent <-->|resources/read| Resources
    Tools --> Client
    Resources --> Client
    Client --> RL
    Client --> Auth
    Auth <--> Store
    Auth <-->|token + refresh| QBO
    Client -->|REST + query| QBO

该服务不保留状态，也不存储客户数据：它是 QuickBooks REST API 的无状态代理。令牌保存在由你控制的本地文件中；客户端使用自己的 Intuit 凭据部署。

工具

每个工具都会返回结构化的 { "ok": true, ... } 结果，或包含 suggestion 的 { "ok": false, "error": {...} }。每个工具都带有 MCP 注释（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）和声明的输出架构。

• create_customer：创建客户。显示名称必须唯一；QuickBooks 会以错误 6240 拒绝重复名称。
• get_customer：按 Id 读取单个客户，包括余额、联系方式和当前 SyncToken。
• update_customer：对现有客户进行稀疏更新。需要 Id 和最新的 SyncToken。
• delete_customer：停用客户（QuickBooks 不支持彻底删除客户），并保留历史记录。
• list_customers：列出客户，按最近更新时间降序排列，并由调用方控制分页。
• search_customers：按显示名称前缀、精确邮箱地址或启用状态查找客户。
• create_invoice：为现有客户创建发票，包含一个或多个明细行。
• get_invoice：按 Id 读取单张发票，包括明细行、总额、余额和当前 SyncToken。
• update_invoice：替换发票。明细行会整体替换，因此请发送最终要保留的所有明细行。
• delete_invoice：永久删除发票。需要 Id 和最新的 SyncToken。
• list_invoices：列出发票，按最近交易日期降序排列，并由调用方控制分页。
• search_invoices：按客户 Id、交易日期范围或单据编号查找发票。
• create_payment：记录收到的付款，可选择将其应用于特定发票。
• get_payment：按 Id 读取单笔付款，包括关联交易和当前 SyncToken。
• update_payment：替换付款。移除发票关联会重新打开该发票的未结余额。
• delete_payment：永久删除付款。任何已结清的发票都将恢复为未付款状态。
• list_payments：列出付款，按最近交易日期降序排列，并由调用方控制分页。
• search_payments：按客户 Id 或交易日期范围查找付款。

资源

只读 JSON：

• qbo://company：公司资料和法定地址
• qbo://summary/receivables：未结／逾期发票数量及未结余额
• qbo://summary/customers：按未结余额排序的活跃客户

最小权限范围

默认范围仅为 com.intuit.quickbooks.accounting。只有在连接支付处理功能时，才通过 QBO_SCOPES 添加 com.intuit.quickbooks.payment。启动时会根据 Intuit 已知范围集合验证范围字符串，因此拼写错误会立即报错，而不会悄悄导致授权不足。除非选择启用，否则绝不会请求身份范围（openid、profile、email）。

速率限制与重试

双令牌桶限流器会同时根据 QuickBooks 每秒和每分钟的上限限制出站流量（可通过 QBO_REQUESTS_PER_SECOND / QBO_REQUESTS_PER_MINUTE 配置）。遇到 429 时，客户端会遵循 Retry-After 标头；遇到没有该标头的 429 / 5xx 时，则会使用带抖动的指数退避，最多重试 QBO_MAX_RETRIES 次。遇到一次 401 时，会触发令牌刷新并自动重试一次。

快速入门

uv venv --python 3.12 .venv
uv pip install -e ".[dev]"

cp .env.example .env       # fill in QBO_CLIENT_ID / QBO_CLIENT_SECRET
mcp-quickbooks auth        # opens Intuit, captures the redirect, stores tokens
mcp-quickbooks status      # verify the token refreshes

mcp-quickbooks stdio       # run over stdio (Claude Desktop)
mcp-quickbooks http --port 8000   # run over Streamable HTTP

凭据会按需读取。即使完全未设置任何 QBO_* 变量，服务也能启动、响应 initialize，并提供 tools/list；没有凭据时调用工具会返回结构化的 401 错误，告知调用方需要配置哪些内容。这样一来，注册表信息查询和容器冒烟测试无需密钥也能正常运行。

Claude Desktop

{
  "mcpServers": {
    "quickbooks": {
      "command": "mcp-quickbooks",
      "args": ["stdio"],
      "env": { "QBO_ENVIRONMENT": "sandbox" }
    }
  }
}

Docker

docker build -t mcp-quickbooks .
docker run --rm -i --env-file .env mcp-quickbooks

连接真实的 Intuit 沙盒

1. 在 Intuit 开发者门户创建应用，然后打开 Keys & OAuth 部分。复制 Development 客户端 ID 和密钥。
2. 添加一个与 .env 中 QBO_REDIRECT_URI 相符的重定向 URI（默认为 http://localhost:8765/callback）。
3. 在开发者控制面板中创建一家沙盒公司；其公司 ID 即为 QBO_REALM_ID。
4. 设置 QBO_ENVIRONMENT=sandbox，填写 QBO_CLIENT_ID / QBO_CLIENT_SECRET，然后运行 mcp-quickbooks auth。浏览器授权流程会自动返回 realmId，并将其与令牌一同保存。
5. 运行 mcp-quickbooks status，确认令牌可以刷新。现在即可操作实时沙盒。

将 QBO_ENVIRONMENT=production（使用生产环境密钥并连接公司）即可连接真实账簿。凭据和令牌归你所有；不会提交任何内容：.env 和 .qbo_tokens.json 已列入 gitignore。

测试

测试套件完全离线运行。所有 QuickBooks 和 OAuth 调用均由内存中的模拟服务（tests/fake_qbo.py）提供，该模拟服务使用 tests/fixtures/ 中仿照录制数据的固定数据，并通过 httpx 模拟传输接入：无需网络，也无需真实凭据。

uv run pytest

注册表元数据

server.json 用于描述 MCP 注册表中的服务，.mcp.json 是目录爬虫会查找的客户端配置片段目录。**发布特意留作手动步骤。**请参阅 PUBLISHING.md。此处不会向任何注册表提交内容。

聘请我

我能让 AI 时代和资金关键型集成达到生产级安全标准：真实的身份验证、真实的速率限制、完善的错误处理和真实的测试。承接 MCP 服务构建和 API 集成加固项目。作品集和联系方式：https://amin-ale.github.io/portfolio-site · [email protected]

许可证

MIT：请参阅 LICENSE。