accountingqb

AccountingQB-MCP

面向 Claude 的功能最全面的 QuickBooks Online MCP 服务。专为希望通过自然对话管理账簿、运行报告和准备税务申报的个体经营者和小型企业打造。

140 个工具，涵盖交易、报告、税务准备（美国和加拿大）、对账、智能记账、1099/T4A 报告、GST/HST 申报、异常检测、贷项通知单、供应商贷项、现金流预测和利润率分析——全部通过 Claude Desktop 完成。还包含 CPA 工作簿：一份 15 页的年终资料册（比较报表、对账核对、已缴税款、所有者提款、税务资料收集表），可导出为 Excel，供会计师使用。

加拿大支持： 开箱即用，适用于加拿大 QuickBooks Online 公司——服务会自动检测公司的税务版本，在创建的交易中应用销售税代码（GST/HST/PST），并提供完整的加拿大税务套件：GST/HST（GST34）申报工作底稿（含 50% 餐饮 ITC 限额）、T2125 行项目映射、T2 公司税工作底稿（GIFI Schedule 125 + Schedule 1 会计账簿与税务调节——仅记录，绝不申报）、CCA 折旧表（半年度规则 + 加速投资激励）、T4A/T5018 承包商报告，以及 CRA 分期缴税 + CPP 估算。多币种公司可查看每笔交易的币种和汇率。

由 Vaspera Capital 打造——因为 QuickBooks 值得拥有一个真正的 MCP 服务。

---

快速开始

前提条件

• Python 3.10+
• QuickBooks Online 账户（任意套餐）
• Claude Desktop
• Intuit Developer 账户（免费注册）

1. 克隆并安装

git clone https://github.com/RCOLKITT/AccountingQB-MCP.git
cd AccountingQB-MCP
pip install -r requirements.txt

2. 创建 Intuit Developer 应用

1. 前往 developer.intuit.com 并登录
2. 点击 Create an App → 选择 QuickBooks Online and Payments
3. 在 Redirect URIs 下，添加：http://localhost:8080/callback
4. 复制你的 Client ID 和 Client Secret

3. 运行设置

python setup.py

设置向导将会：

• 询问你的 Client ID 和 Client Secret
• 打开浏览器，以授权访问你的 QuickBooks 公司
• 自动接收 OAuth 回调
• 写入你的 Claude Desktop 配置
• 验证连接是否正常

就是这样。重启 Claude Desktop，即可连接。

手动配置（高级）

如果你更喜欢手动配置，请将以下内容添加到 Claude Desktop 配置中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "accountingqb": {
      "command": "python3",
      "args": ["/path/to/AccountingQB-MCP/server.py"],
      "env": {
        "QB_CLIENT_ID": "your_client_id",
        "QB_CLIENT_SECRET": "your_client_secret",
        "QB_REALM_ID": "your_company_id",
        "QB_REFRESH_TOKEN": "your_refresh_token",
        "QB_ENVIRONMENT": "production"
      }
    }
  }
}

要手动获取刷新令牌，请使用 Intuit OAuth Playground。

---

工具（130）

公司与实体

工具	描述
qb_company_info	公司名称、EIN、地址、财年
qb_list_accounts	完整科目表及余额
qb_list_classes	列出类别（类别跟踪分类）
qb_list_departments	列出部门/地点（地点跟踪）
qb_list_vendors	搜索供应商
qb_list_customers	搜索客户
qb_list_items	产品和服务
qb_create_vendor	创建供应商
qb_create_customer	创建客户
qb_update_vendor	更新供应商详情（电子邮件、电话、地址）
qb_update_customer	更新客户详情（电子邮件、电话、地址）
qb_create_account	在科目表中添加科目
qb_create_sub_account	在上级科目下创建子科目
qb_inactivate_account	隐藏未使用的科目

交易

工具	描述
qb_list_transactions	按筛选条件列出采购／费用
qb_list_deposits	收入和所有者投资
qb_list_transfers	账户间转账
qb_list_journal_entries	调整和重新分类
qb_list_journal_entries_by_memo	按备注文本搜索 JE
qb_list_bills	应付账款
qb_list_bill_payments	账单付款
qb_list_sales_receipts	直接销售
qb_list_payments	收到的客户付款
qb_list_invoices	按状态筛选发票
qb_list_credit_memos	客户贷项通知单／退款
qb_list_vendor_credits	收到的供应商贷项
qb_list_estimates	按状态筛选估价单／报价单
qb_search_transactions	搜索所有交易类型
qb_list_purchase_orders	列出采购订单——供应商、金额、Open／Closed 状态
qb_list_recurring_transactions	定期交易模板和计划
qb_transaction_detail	查看任意单笔交易的完整详情
qb_account_transactions	查看影响特定账户的所有交易

创建和修改

工具	描述
qb_create_expense	记录采购／费用
qb_create_invoice	创建客户发票
qb_create_bill	创建供应商账单
qb_create_estimate	创建客户估价单／报价单
qb_create_journal_entry	记录调整
qb_create_deposit	记录银行存款
qb_create_transfer	在账户间转账
qb_create_credit_memo	开具客户贷项通知单
qb_create_vendor_credit	记录供应商贷项
qb_convert_estimate_to_invoice	将估价单转换为发票
qb_record_bill_payment	记录供应商账单付款
qb_record_invoice_payment	记录客户发票付款
qb_update_transaction	更新任意交易
qb_void_transaction	作废交易
qb_delete_transaction	永久删除交易
qb_delete_journal_entry	永久删除 JE
qb_reclassify_transaction	将交易转移到其他账户
qb_bulk_update_vendor	批量为多笔交易指定供应商
qb_bulk_update_vendors_multi	一次调用即可批量指定多个供应商
qb_batch_create_expenses	批量导入费用
qb_batch_create_bills	批量导入账单
qb_batch_create_journal_entries	批量导入 JE

报告与分析

工具	描述
qb_profit_loss	按总计、月、季度或年度查看损益
qb_profit_loss_detail	损益明细下钻 — 按账户列出每个项目背后的所有交易
qb_profit_loss_by_class	按类别（细分市场／项目）拆分损益
qb_profit_loss_by_department	按部门／地点拆分损益
qb_vendor_expenses	按供应商汇总支出（VendorExpenses 报告）
qb_balance_sheet	查看任意日期的资产负债表
qb_sales_by_customer	按客户汇总销售额（收入）
qb_sales_by_product	按产品／服务查看销售额 — 数量和金额
qb_sales_by_class	按类别（细分市场／项目）拆分销售额
qb_sales_by_department	按部门／地点拆分销售额
qb_inventory_valuation	查看指定日期的库存现有数量、资产价值和平均成本
qb_transaction_list	灵活查询指定日期范围内的交易登记簿
qb_customer_balance_detail	按客户列出未结发票及明细行（应收账款下钻）
qb_vendor_balance_detail	按供应商列出未结账单及明细行（应付账款下钻）
qb_cash_flow	现金流量表
qb_cash_flow_forecast	多期间现金流预测
qb_general_ledger	按账户列出所有交易
qb_trial_balance	验证账目是否平衡
qb_ar_aging	客户欠款情况
qb_ap_aging	欠供应商的款项
qb_expense_summary	按类别汇总支出
qb_income_summary	按来源汇总收入
qb_sales_tax_summary	按辖区汇总已收销售税
qb_sales_tax_nexus	经济关联门槛检查 — 按收货州查看销售额，与各州设定的 Wayfair 门槛比较，并查看各州应纳税额
qb_compare_periods	并排比较不同期间
qb_vendor_summary	按支出列出主要供应商
qb_profit_margin_analysis	按客户或项目分析利润率
qb_budget_vs_actual	比较预算与实际支出
qb_anomaly_detection	统计异常与欺诈检测

税务准备

工具	描述
qb_tax_summary	将支出映射至 Schedule C 项目
qb_schedule_c	完整的 IRS Schedule C 逐项明细
qb_schedule_c_detailed	详细的 Schedule C，包含 QB 账户明细
qb_estimate_quarterly_tax	联邦和州预估税款
qb_deduction_finder	查找常被遗漏的抵扣项
qb_depreciation_schedule	Section 179 和 MACRS 折旧表
qb_1099_contractor_report	1099-NEC 承包商申报，并验证 TIN／地址
qb_home_office_calculator	Form 8829 家庭办公室抵扣计算器
qb_vehicle_depreciation_calculator	按商业用途比例计算车辆折旧
qb_payroll_checklist	薪资申报边界检查清单 — 薪资／负债信号，以及需交给 CPA 处理的 W-2／1099、941／940 项目

加拿大税务（GST/HST、T2125、T2）

工具	描述
qb_gst_hst_return	GST34 申报工作底稿 — 第 101／103／105／106／108／109 行，包含 50% 餐费进项税抵免限制、TaxSummary 报告、税款缴纳记录和简易计算方法说明
qb_t2125_summary	CRA T2125 逐项映射（8521 广告、8523 餐费按 50% 计算、8910 租金……）
qb_t2_summary	CRA T2 公司税工作底稿 — GIFI Schedule 125 损益表及 Schedule 1 会计利润与应税利润调节表（折旧摊销第 104 行、餐费按 50% 计算第 121 行、CCA 第 403 行）；仅记录，不申报
qb_cca_schedule	按类别列示资本成本津贴 — 半年规则、加速投资激励、Class 10.1／54 上限
qb_t4a_contractor_report	T4A 第 048 栏承包商申报，并验证 BN／地址（建筑行业 T5018 说明）
qb_estimate_instalments	CRA 分期缴款（3 月／6 月／9 月／12 月 15 日）及精确 CPP／CPP2，并估算联邦／省税款
qb_list_tax_codes	销售税代码（名称、综合税率、机构）— 将其作为 tax_code= 传递给创建工具
qb_list_tax_rates	单项销售税率及机构

智能功能

工具	描述
qb_uncategorized_transactions	查找未分类的交易
qb_find_duplicates	检测可能重复的记录
qb_auto_categorize_suggestions	根据供应商历史记录提供 AI 分类建议
qb_monthly_burn_rate	月度支出趋势
qb_runway_calculator	现金可支撑的月数
qb_fiscal_year_close_checklist	年终结账准备情况检查
qb_books_health_audit	全面的账簿健康状况审计
qb_books_hygiene	结构审计：已删除账户的入账记录、符号错误的余额、错误归类的信用卡付款、休眠余额、对账单确认
qb_month_end_close	月末结账清单及状态检查
qb_unknown_vendor_report	查找缺少供应商名称的交易

对账与附件

工具	描述
qb_reconcile_invoices	将发票与 QB 交易匹配
qb_match_invoices_to_transactions	在容差范围内进行模糊匹配
qb_upload_receipt	将收据附加到交易
qb_list_attachments	列出已附加的文档
qb_missing_receipts	无附加收据且金额 ≥ 阈值（默认为 $75）的支出 — IRS 凭证支持缺口
qb_change_audit_trail	查看自某日期以来的变更 — 已创建／已更新／已删除的交易（QuickBooks CDC）
qb_bank_reconciliation	将银行／信用卡对账单 CSV 与账簿核对 — 已匹配／缺失／未结清
qb_stripe_reconcile	对账 Stripe 活动 — 通过清算账户净额处理手续费和平台费用（Sigma/Billing/Radar），并与 Stripe 余额核对
qb_account_balance	检查任意账户余额

连接与多公司

工具	描述
qb_list_companies	列出所有已连接的 QuickBooks 公司
qb_switch_company	切换到另一家公司
qb_refresh_connection	刷新与 AccountingQB 的连接

---

使用示例

连接后，只需自然地向 Claude 提问：

• “我 2025 年的损益表是什么？”
• “显示上个月所有超过 $500 的支出”
• “为 GitHub 创建一笔 $49.99 的软件订阅支出”
• “生成我 2025 纳税年度的 Schedule C”
• “查找任何未分类的交易”
• “我的月度资金消耗率是多少？”
• “我的现金还能支撑多久？”
• “比较第一季度和第二季度的损益”
• “查找可能重复的交易”
• “我遗漏了哪些抵扣项？”
• “生成我的 1099 承包商报告”
• “对上一季度的交易运行异常检测”
• “按客户显示我的利润率”
• “预测未来 6 个月的现金流”
• “为 Amazon 创建一笔 $200 的供应商贷项”
• “将报价单 #1042 转换为发票”
• “为第二季度编制我的 GST/HST 申报工作底稿”（加拿大）
• “将我的账簿映射到 T2125，并估算我的 CRA 分期付款”（加拿大）

---

安全性

此服务非常重视安全性：

• 代码中不存储凭据 — 所有机密信息均来自环境变量
• OAuth 2.0，并自动轮换令牌
• 仅限本地的 OAuth 流程 — 设置脚本会在 127.0.0.1 上运行回调服务
• .env 文件已加入 gitignore，并设置为 chmod 600（仅所有者可访问）
• 不存储数据 — 此服务为无状态服务；它只读取／写入 QuickBooks，不执行其他操作
• 刷新令牌会轮换 — 每次令牌交换都会返回新的刷新令牌
• 有效期为 100 天 — 令牌在 100 天不活动后过期（Intuit 政策）

令牌管理

QuickBooks 刷新令牌有效期为 100 天，并会在每次使用时自动轮换，因此活跃连接可以一直保持有效。如果连接确实失效（闲置 100 天以上），请根据使用 AccountingQB 的方式重新连接：

• 托管 / 代管（你持有许可证密钥）： 在 Claude 中先运行 qb_refresh_connection——它会在后台重新建立大多数已过期的连接，无需打开浏览器。如果连接已完全失效，请前往 accountingqb.com/dashboard → Connect QuickBooks 重新连接，然后再次运行 qb_refresh_connection。
• 自托管（你自己的 Intuit 应用）： 重新运行 python setup.py，以重新授权并改写刷新令牌。

---

沙盒模式

连接到生产环境之前，先使用 Intuit 的沙盒进行测试：

python setup.py --sandbox

此操作会连接到 sandbox-quickbooks.api.intuit.com，并使用 Intuit 的测试数据。准备就绪后，不带该标志再次运行 setup，即可切换到生产环境。

---

故障排除

“QuickBooks credentials not configured” 自托管：运行 python setup.py 配置凭据，或检查 Claude Desktop 配置。托管 / 代管：设置你的 QB_LICENSE_KEY，并在 accountingqb.com/dashboard 连接一家公司。

“401 Unauthorized” 你的连接可能已过期（闲置期限为 100 天）。托管 / 代管：先运行 qb_refresh_connection，然后如有需要，前往 accountingqb.com/dashboard → Connect QuickBooks 重新连接。自托管：重新运行 python setup.py 以重新授权。

“Company not found” 请检查 QB_REALM_ID 是否与已授权的公司相符。登录 QuickBooks Online 后，可以在 URL 中找到该 ID。

Claude Desktop 中未显示工具 运行 setup 后重启 Claude Desktop。请检查 Claude Desktop 配置中是否存在 accountingqb 条目。

沙盒与生产环境 如果你看到的是测试数据，请检查配置中 QB_ENVIRONMENT 是否设为 "production"。

---

贡献

欢迎提交问题和 PR。如果要添加新工具，请遵循现有模式：

• 使用扁平参数（而非 Pydantic 模型），以兼容 Claude Desktop
• 添加描述性文档字符串
• 以易于采取行动的消息妥善处理错误
• 将工具添加到 README 表格中

---

许可证

专有软件 — © Vaspera Capital LLC，保留所有权利。 源代码公开可见，以便进行透明度和安全审查；但它并非开源软件。使用需要付费许可证密钥。请参阅 LICENSE。

由 Vaspera Capital 构建