quickbooks-mcp

QuickBooks MCP Server

面向 QuickBooks Online 的 MCP 服务，专为在日常工作流中使用 AI 助手的簿记员、CFO 和会计师打造。

你可以用日常语言让 AI 助手提取损益表、创建日记账分录或调查账户余额，而无需编写 API 载荷。

为什么选择此服务？

Intuit 提供了一个官方 MCP 服务，是开发者探索 QuickBooks API 的良好起点。此服务采用不同的方式：专为在生产账簿中工作的财务专业人士设计。

使用自然语言，而不是内部 ID

Intuit 的服务要求每个引用都使用 QuickBooks 内部 ID——创建账单前，你需要先查找供应商的 ID。此服务会自动解析名称：

"Create a bill for PG&E, $450 to Utilities, dated 2025-01-15"
→ Vendor, account, and department names are resolved automatically

内置财务报告

这是唯一提供报告工具的 QuickBooks MCP 服务。你可以提取损益表、资产负债表或试算平衡表，并按月份、部门或类别细分，无需离开 AI 对话。

默认安全

每项创建和编辑操作默认使用草稿／预览模式。提交前，你可以准确查看将写入账簿的内容。不会意外创建日记账分录，也不会错误分类支出。

一个查询工具，替代数十个工具

无需为每种实体类型使用单独的搜索工具，一个类 SQL 的 query 工具即可查询所有 QuickBooks 实体。AI 助手可以自然地编写 SQL，由 QuickBooks 负责验证——无需维护字段白名单。

"SELECT * FROM Purchase WHERE TxnDate >= '2025-01-01' AND TxnDate <= '2025-01-31'"

面向生产环境的凭据管理

个人使用时可在本地存储凭据；共享环境中则可使用 AWS Secrets Manager。OAuth 令牌会自动刷新并跨会话持久保存。

一览

	Intuit 官方服务	此服务
目标用户	探索 API 的开发者	簿记员、CFO、会计师
名称解析	需要 QB 内部 ID	自动解析名称
财务报告	无	损益表、资产负债表、试算平衡表
写入安全性	立即执行	默认提供草稿预览
查询方式	按实体分类的搜索工具	使用类 SQL 查询查询所有实体
凭据	本地 .env 文件	本地文件或 AWS Secrets Manager
分发方式	从 GitHub 克隆	npx quickbooks-mcp

先决条件

• QuickBooks Developer Account：在 developer.intuit.com 注册
• Node.js 18+

安装选项

选择适合你使用场景的设置方式：

设置方式	适用场景
NPM 安装	快速设置，使用自己的 QuickBooks 应用
本地检出	开发、自定义
AWS 模式	共享／生产环境

---

选项 1：NPM 安装

最简单的入门方式。凭据存储在你的本机上。

1. 创建 QuickBooks 应用

1. 前往 developer.intuit.com 并登录
2. 创建新应用（或选择现有应用）
3. 前往“Keys & credentials”
4. 记下你的 Client ID 和 Client Secret
5. 在“Redirect URIs”下添加：https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl

2. 添加到 Claude Code

将以下内容添加到项目的 .mcp.json：

{
  "mcpServers": {
    "quickbooks": {
      "command": "npx",
      "args": ["-y", "quickbooks-mcp"]
    }
  }
}

3. 配置凭据

创建 ~/.quickbooks-mcp/credentials.json：

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

4. 进行身份验证

Claude Code 运行后，使用 qbo_authenticate 工具：

1. 不带参数调用 qbo_authenticate，获取授权 URL
2. 在浏览器中打开该 URL 并授权应用
3. 从重定向 URL 中复制 code 和 realmId
4. 再次调用 qbo_authenticate，并提供授权码和 realm ID

你的 OAuth 令牌将会保存并自动刷新。

---

选项 2：本地检出

适用于开发或自定义。

1. 创建 QuickBooks 应用

按照上方选项 1 的相同步骤操作。

2. 克隆并构建

git clone https://github.com/laf-rge/quickbooks-mcp.git
cd quickbooks-mcp
npm install
npm run build

3. 添加到 Claude Code

添加到项目的 .mcp.json：

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/path/to/quickbooks-mcp/dist/index.js"]
    }
  }
}

4. 配置凭据

使用你的客户端凭据创建 ~/.quickbooks-mcp/credentials.json（与选项 1 相同），然后运行 qbo_authenticate 完成 OAuth 流程。

---

选项 3：AWS 模式

适用于共享或生产环境。凭据存储在 AWS Secrets Manager 中。

1. 创建 AWS 资源

在 Secrets Manager 中创建密钥：

aws secretsmanager create-secret \
  --name prod/qbo \
  --secret-string '{
    "client_id": "your_client_id",
    "client_secret": "your_client_secret",
    "access_token": "your_access_token",
    "refresh_token": "your_refresh_token",
    "redirect_url": "https://developer.intuit.com/v2/OAuth2Playground/RedirectUrl"
  }'

在 SSM Parameter Store 中存储公司 ID：

aws ssm put-parameter \
  --name /prod/qbo/company_id \
  --value "your_company_id" \
  --type SecureString

2. 配置服务

在 quickbooks-mcp 目录中创建 .env 文件：

QBO_CREDENTIAL_MODE=aws
AWS_REGION=us-east-2
QBO_SECRET_NAME=prod/qbo
QBO_COMPANY_ID_PARAM=/prod/qbo/company_id

注意：由于存在一个已知的 Claude Code 错误，.mcp.json 中的环境变量无法可靠地传递给 MCP 服务。必须使用 .env 文件作为解决方法。

3. 添加到 Claude Code

{
  "mcpServers": {
    "quickbooks": {
      "command": "node",
      "args": ["/path/to/quickbooks-mcp/dist/index.js"]
    }
  }
}

4. IAM 权限

服务需要以下 AWS 权限：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:PutSecretValue"
      ],
      "Resource": "arn:aws:secretsmanager:*:*:secret:prod/qbo*"
    },
    {
      "Effect": "Allow",
      "Action": ["ssm:GetParameter"],
      "Resource": "arn:aws:ssm:*:*:parameter/prod/qbo/*"
    }
  ]
}

---

内联输出模式

默认情况下，大型响应（报告、查询结果）会写入 /tmp 文件，服务会返回文件路径。这在终端环境中的 Claude Code 中运行良好，但在 Claude Desktop 和 插件环境中会失效，因为模型无法读取 /tmp 中的文件。

设置 QBO_INLINE_OUTPUT=true，即可改为内联返回所有响应。

选项 A — 通过 .env 文件（本地检出时推荐）：

在 quickbooks-mcp 目录中创建 .env 文件：

QBO_INLINE_OUTPUT=true

选项 B — 通过 .mcp.json env 块（NPM 安装时推荐）：

{
  "mcpServers": {
    "quickbooks": {
      "command": "npx",
      "args": ["-y", "quickbooks-mcp"],
      "env": {
        "QBO_CREDENTIAL_MODE": "local",
        "QBO_INLINE_OUTPUT": "true"
      }
    }
  }
}

注意：由于存在一个已知的 Claude Code 错误，在某些配置下，.mcp.json 中的环境变量无法可靠地传递给 MCP 服务。如果选项 B 不起作用，请使用 .env 文件作为解决方法。

---

环境变量

变量	默认值	说明
QBO_CREDENTIAL_MODE	local	凭据存储方式：local 或 aws
QBO_CLIENT_ID	-	QuickBooks 应用客户端 ID（本地模式）
QBO_CLIENT_SECRET	-	QuickBooks 应用客户端密钥（本地模式）
QBO_CREDENTIAL_FILE	~/.quickbooks-mcp/credentials.json	自定义凭据文件路径。开头的 ~ 会展开为你的主目录，因此即使 MCP 客户端的 JSON env 块中没有 shell 来展开它，也能正常使用。
QBO_INLINE_OUTPUT	false	内联返回响应，而不是写入 /tmp 文件。在 Claude Desktop 或插件环境中使用时，由于模型无法访问基于文件的输出，因此必须启用此选项。
QBO_SANDBOX	false	使用 QuickBooks 沙盒环境。同时会将“在 QuickBooks 中查看”的深层链接切换为 app.sandbox.qbo.intuit.com，确保无法打开生产公司。
AWS_REGION	us-east-2	AWS 区域（aws 模式）
QBO_SECRET_NAME	prod/qbo	Secrets Manager 密钥名称（aws 模式）
QBO_COMPANY_ID_PARAM	/prod/qbo/company_id	SSM 参数路径（aws 模式）

---

可用工具

工具	描述
设置
qbo_authenticate	设置 OAuth 凭据（仅限本地模式）
get_company_info	获取已连接公司的信息
查询与报告
query	对任意 QuickBooks 实体运行类似 SQL 的查询
list_accounts	按筛选条件列出会计科目表
get_profit_loss	损益报告（按月、部门、类别等）
get_balance_sheet	资产负债表报告
get_trial_balance	试算平衡表报告（flags: true 会增加结账复核步骤，用于检查余额方向错误及未分类／暂记余额）
get_report	其他 24 种 QuickBooks 报告中的任意一种——应收账款和应付账款账龄、客户和供应商余额、交易列表、总账、日记账、按客户／项目／类别／部门划分的销售额、现金流，以及明细变体
query_account_transactions	影响特定科目的所有交易（13 种过账实体类型，支持分页，可选汇总子科目；限制请参见 docs/entity-coverage.md）
account_period_summary	科目的期间汇总（期初／期末余额、借方、贷方、计数）
日记账分录
create_journal_entry	创建日记账分录（验证借方 = 贷方；分录行使用 entity_name/entity_type）
get_journal_entry	按 ID 获取日记账分录
edit_journal_entry	修改现有日记账分录
账单
create_bill	创建供应商账单（分录行使用 customer_name）
get_bill	按 ID 获取账单
edit_bill	修改现有账单
费用
create_expense	创建费用（现金、支票或信用卡；收款方可以是供应商、客户或员工）
get_expense	按 ID 获取费用
edit_expense	修改现有费用
销售收据
create_sales_receipt	创建包含项目明细行的销售收据
get_sales_receipt	按 ID 获取销售收据
edit_sales_receipt	修改现有销售收据
发票
create_invoice	创建包含项目明细行的发票（必须指定客户）
get_invoice	按 ID 获取发票
edit_invoice	修改现有发票
存款
create_deposit	创建银行存款（分录行使用 entity_name/entity_type）
get_deposit	按 ID 获取存款
edit_deposit	修改现有存款（分录行使用 entity_name/entity_type）
供应商贷项
create_vendor_credit	创建供应商贷项（分录行使用 customer_name）
get_vendor_credit	按 ID 获取供应商贷项
edit_vendor_credit	修改现有供应商贷项
账单付款
create_bill_payment	支付账单并应用供应商贷项（QBO 的“支票”／支付账单流程）
receive_payment	记录客户对未结发票的付款（对应 create_bill_payment 的应收账款流程）；每个分录行默认采用发票的未结余额
create_transfer	在公司自有的两个账户之间转账（银行账户↔银行账户、偿还信用卡欠款）
get_bill_payment	按 ID 获取账单付款；标记未应用金额
供应商
create_vendor	创建供应商（联系人、账单地址、付款条件、账号、1099 标记）
edit_vendor	对供应商进行稀疏更新；active: false 会停用供应商。使用 query 读取供应商
删除
delete_entity	删除任意交易（日记账分录、账单、发票、存款、销售收据、费用、供应商贷项、账单付款）

为供应商、客户和员工命名

每个可将明细行或表头归属到名称列表中的写入工具，都接受名称并将其解析为 ID，方式与 account_name 和 department_name 相同。具体使用哪个参数，取决于 QuickBooks 实际会在对应位置存储什么：

参数	适用位置	接受的类型
entity_name + entity_type	create_deposit / edit_deposit 明细行，create_journal_entry / edit_journal_entry 明细行，create_expense / edit_expense 表头收款方	供应商、客户或员工。entity_type 默认为 Vendor。
customer_name	create_bill / edit_bill、create_expense / edit_expense、create_vendor_credit / edit_vendor_credit 明细行	仅限客户——QuickBooks 会在这些明细行上存储 CustomerRef，且不支持供应商或员工。
vendor_name	create_bill、create_vendor_credit、create_bill_payment 表头	仅限供应商。
customer_name（表头）	create_invoice、create_sales_receipt	仅限客户。这些工具的商品明细行没有逐行实体。

如果你已知内部 ID，也可以使用各参数对应的 _id 形式（entity_id、customer_id）。对于编辑工具，明细行参数的规则如下：

• 省略该参数时，由 line_id 指定的明细行会保留已有实体；
• 指定名称时，会设置或替换该实体；
• 传入空字符串（entity_name: ""）时，会清除该实体。

有关底层 QBO 字段结构（这些结构并不统一），请参阅 docs/quickbooks-api-limitations.md。

强制校验参数名称

在任何操作运行前，都会根据每个工具声明的架构检查参数。未知参数会报错并指出最接近的有效参数；缺少必需参数会报错；没有任何字段需要修改的 edit_* 调用也会报错，而不会执行写入并报告成功。

另一种做法是默默忽略。处理程序只读取它认识的参数，因此拼错的参数会被直接忽略：创建调用将日期放在错误的键下，会按今天的日期提交；要求指定日期范围的截至日期报表会返回今天的余额；所有字段都拼错的编辑调用会返回“更新成功”，但实际上什么也没改。调用方不会收到任何提示。

另外，当 QuickBooks 接受更新但没有递增记录的 SyncToken（也就是说，提交的数据与已存储的数据相同）时，编辑工具会报告未发生更改，而不是报告成功。

---

令牌刷新

服务器会在每次请求时自动刷新 OAuth 令牌，并将其持久化到你的凭据存储中（本地文件或 AWS Secrets Manager）。

---

开发

npm run dev      # Run in development mode
npm run build    # Build
npm run typecheck # Type check
npm test         # Run the test suite

测试位于 tests/，目录结构与 src/ 一致。测试使用 TypeScript，由 tsconfig.test.json 编译到 dist-test/，并通过 Node 内置的测试运行器运行——无需依赖测试框架。测试中的类型错误会导致构建失败，因此引用已重命名导出的测试会明确报错，而不会被静默跳过。凡是需要 QuickBooks 客户端的测试，都会使用手写的替代实现，仅覆盖被测调用，因此测试套件可以在离线且无凭据的情况下运行。

---

故障排查

“QuickBooks credentials not configured”

运行 qbo_authenticate 工具以设置 OAuth 凭据（仅限本地模式）。

“Authorization code expired”

授权码仅在几分钟内有效。请重新启动 OAuth 流程。

令牌刷新失败

• 检查你的刷新令牌是否已过期（约 100 天）
• 确认客户端凭据正确
• 尝试使用 qbo_authenticate 重新进行身份验证

AWS 凭据错误

• 确保 .env 文件中设置了 QBO_CREDENTIAL_MODE=aws
• 检查你的 AWS 凭据和权限
• 确认密钥和参数名称与你的配置一致