QuickBooks Online

@mindstone/mcp-server-quickbooks

面向 Model Context Protocol 宿主的 QuickBooks Online MCP 服务。通过标准化的 MCP 接口管理 QuickBooks Online 中的发票、账单、客户、供应商、员工和账户。

状态

• 版本： 0.4.3 · npm
• 身份验证： OAuth (QUICKBOOKS_REFRESH_TOKEN)
• 工具： 21（客户、供应商、发票、账单、报价单、报告）
• 服务类型： cloud-api
• 机器可读： STATUS.json

默认启用生产环境写入

每个会修改 QuickBooks 的工具 （create_quickbooks_invoice、create_quickbooks_bill、 create_quickbooks_customer、create_quickbooks_vendor、 create_quickbooks_estimate、send_quickbooks_invoice_email、 update_quickbooks_invoice、update_quickbooks_customer、 update_quickbooks_vendor）都会直接执行写入操作，无需选择启用： 此功能默认启用，宿主的工具审批层负责把关。只读工具（list_*、get_*、query_*、download_*、 configure_quickbooks）不受影响。

0.3.0–0.4.0 版本通过 QB_ALLOW_PROD_WRITES=1 环境变量限制这些写入操作。该限制现已移除；程序不再读取此变量， 可从宿主配置中删除。

要求

• Node.js 20+
• npm

一键安装

点击按钮后，宿主会提示你填写：QUICKBOOKS_CLIENT_ID、QUICKBOOKS_CLIENT_SECRET、QUICKBOOKS_REFRESH_TOKEN、QUICKBOOKS_REALM_ID、QUICKBOOKS_ENVIRONMENT。

{
  "mcpServers": {
    "QuickBooks Online": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-quickbooks"
      ],
      "env": {
        "QUICKBOOKS_CLIENT_ID": "",
        "QUICKBOOKS_CLIENT_SECRET": "",
        "QUICKBOOKS_REFRESH_TOKEN": "",
        "QUICKBOOKS_REALM_ID": "",
        "QUICKBOOKS_ENVIRONMENT": "production"
      }
    }
  }
}

快速开始

安装和构建

cd <path-to-repo>/connectors/quickbooks
npm install
npm run build

npx（发布后）

npx -y @mindstone/mcp-server-quickbooks

本地

node dist/index.js

配置

环境变量

• QUICKBOOKS_CLIENT_ID — Intuit Developer 应用客户端 ID
• QUICKBOOKS_CLIENT_SECRET — Intuit Developer 应用客户端密钥
• QUICKBOOKS_REFRESH_TOKEN — OAuth 2.0 刷新令牌
• QUICKBOOKS_REALM_ID — QuickBooks 公司（realm）ID
• QUICKBOOKS_ENVIRONMENT — sandbox 或 production（默认值：production）
• MCP_HOST_BRIDGE_STATE — 主机桥接状态文件的可选路径，用于凭据管理
• MINDSTONE_REBEL_BRIDGE_STATE — MCP_HOST_BRIDGE_STATE 的向后兼容别名

主机配置示例

Claude Desktop / Cursor

{
  "mcpServers": {
    "QuickBooks": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-quickbooks"],
      "env": {
        "QUICKBOOKS_CLIENT_ID": "your-client-id",
        "QUICKBOOKS_CLIENT_SECRET": "your-client-secret",
        "QUICKBOOKS_REFRESH_TOKEN": "your-refresh-token",
        "QUICKBOOKS_REALM_ID": "your-realm-id"
      }
    }
  }
}

本地开发（无需发布到 npm）

{
  "mcpServers": {
    "QuickBooks": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/quickbooks/dist/index.js"],
      "env": {
        "QUICKBOOKS_CLIENT_ID": "your-client-id",
        "QUICKBOOKS_CLIENT_SECRET": "your-client-secret",
        "QUICKBOOKS_REFRESH_TOKEN": "your-refresh-token",
        "QUICKBOOKS_REALM_ID": "your-realm-id"
      }
    }
  }
}

工具（21）

配置

• configure_quickbooks — 配置 QuickBooks Online OAuth 凭据

查询

• query_quickbooks — 使用 QuickBooks Query Language 运行 QuickBooks 查询
• get_quickbooks_entity — 按类型和 ID 获取单个实体

报表

• get_quickbooks_report — 运行财务报表（ProfitAndLoss、BalanceSheet、CashFlow、AgedReceivables、AgedPayables）

客户

• list_quickbooks_customers — 列出客户
• create_quickbooks_customer — 新建客户
• update_quickbooks_customer — 稀疏更新客户（使用 active: false 停用）

供应商

• list_quickbooks_vendors — 列出供应商
• create_quickbooks_vendor — 新建供应商
• update_quickbooks_vendor — 稀疏更新供应商（使用 active: false 停用）

发票

• list_quickbooks_invoices — 列出发票
• create_quickbooks_invoice — 新建发票
• update_quickbooks_invoice — 稀疏更新发票标题字段（dueDate、memo、privateNote）
• send_quickbooks_invoice_email — 将发票通过电子邮件发送给对应客户
• download_quickbooks_invoice_pdf — 将发票下载为 PDF（保存到系统临时目录）

报价单

• list_quickbooks_estimates — 列出报价单（quotes）
• create_quickbooks_estimate — 新建报价单

账单

• list_quickbooks_bills — 列出账单（应付账款）
• create_quickbooks_bill — 新建账单

员工

• list_quickbooks_employees — 列出员工

科目

• list_quickbooks_accounts — 列出会计科目表

不可信内容封装

QuickBooks 中的文本（客户/供应商显示名称、备注、行描述、报表单元格）可能受到攻击者影响，因此连接器会在将其返回给模型之前，将其封装在 <untrusted-content source="quickbooks:…"> 中。类型化实体载荷采用默认拒绝策略进行清理：除非键属于范围严格限定的结构性谓词（ID、SyncToken、日期/时间戳、枚举），且值通过形状检查，否则每个字符串都会被封装，包括数组中的字符串（它们没有键上下文）。query_quickbooks、get_quickbooks_entity 和报表会将每个字符串键和值整体封装。Id、SyncToken、日期和金额等结构性值保持原样，以便在后续调用中继续使用。

许可证

FSL-1.1-MIT — Functional Source License，Version 1.1，未来将采用 MIT 许可证。本软件将于 2030-04-08 转为 MIT 许可证。