quickbooks-mcp-server

QuickBooks MCP 服务

将 Claude Desktop 和 Claude Code 连接到 QuickBooks Online，实现自然语言会计操作。使用日常语言询问发票、费用、报告等信息。

---

这是什么？

一个 MCP（Model Context Protocol） 服务，可让 Claude 直接访问你的 QuickBooks Online 数据。无需登录 QuickBooks 并逐个点击查看报告，只需询问 Claude：

“列出所有逾期发票，并按金额排序” “我们本季度的损益情况如何？” “为 Acme Corp 创建一张金额为 $2,500 的发票”

此服务负责处理 OAuth 身份验证、API 调用、速率限制和数据格式化。

---

快速开始

1. 安装

pip install quickbooks-mcp

或者从源代码安装：

git clone https://github.com/nyxtools/quickbooks-mcp-server.git
cd quickbooks-mcp-server
pip install -e .

2. 创建 QuickBooks Developer App

1. 前往 developer.intuit.com
2. 创建应用，并选择 QuickBooks Online and Payments
3. 在 Keys & OAuth 下记下你的 Client ID 和 Client Secret
4. 添加 http://localhost:8080/callback 作为 Redirect URI

3. 设置环境变量

export QBO_CLIENT_ID='your_client_id'
export QBO_CLIENT_SECRET='your_client_secret'

4. 运行 OAuth 设置

python scripts/setup_oauth.py

这会打开浏览器，通过 QuickBooks 授权，并在本地存储令牌（已加密）。记下最后显示的 Realm ID。

export QBO_REALM_ID='your_realm_id'

5. 配置 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "quickbooks": {
      "command": "quickbooks-mcp",
      "env": {
        "QBO_CLIENT_ID": "your_client_id",
        "QBO_CLIENT_SECRET": "your_client_secret",
        "QBO_REALM_ID": "your_realm_id"
      }
    }
  }
}

配置文件位置：

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

6. 开始使用

重启 Claude Desktop，然后试试：

“我的银行账户当前余额是多少？”

---

全部 19 个工具

免费版（9 个工具）

工具	说明
list_invoices	按状态、日期和客户列出并筛选发票
get_invoice_details	发票完整详情，包括明细项和付款记录
get_overdue_invoices	列出所有逾期发票，并按逾期天数排序
list_expenses	列出费用，可按日期、供应商、金额和类别筛选
get_top_expenses	按类别或供应商汇总任意时段的主要费用
get_account_balances	显示银行、信用卡或所有账户的当前余额
get_account_transactions	显示任意账户近期交易，可按日期筛选
search_customers	按姓名或电子邮件搜索客户，并显示联系信息
get_customer_summary	客户财务摘要：已开票金额、已付款金额和未结金额

高级版（10 个工具）-- $29/月

工具	说明
get_profit_and_loss	查看任意时段的损益报告及收入、费用明细
get_balance_sheet	查看任意日期的资产负债表（资产、负债、权益）
get_cash_flow	查看现金流量表（经营、投资、融资）
get_accounts_receivable_aging	按客户查看应收账款账龄（当前/30/60/90+ 天）
get_accounts_payable_aging	按供应商查看应付账款账龄（当前/30/60/90+ 天）
create_invoice	创建发票，可设置明细项、到期日和备注
record_payment	记录发票付款，可填写方式和参考信息
create_expense	记录费用，可填写供应商、金额、类别和日期
get_financial_health	关键比率：流动比率、DSO、消耗率、资金可支撑时间
compare_periods	并排比较不同期间，并显示百分比变化

在 nyxtools.dev/quickbooks-mcp 获取高级版许可证

在环境中设置：

export LICENSE_KEY='your_license_key'

---

使用示例

发票

“列出一月份的所有发票” “哪些发票逾期了？先显示逾期最严重的” “查看编号为 #1042 的发票详情” “列出 Acme Corp 的未结发票”

支出

“我们本月花了多少钱？” “显示本季度支出最多的 10 个类别” “我们今年在 Amazon 花了多少钱？”

账户

“我们的银行余额是多少？” “显示支票账户最近的 20 笔交易” “我们的公司信用卡余额是多少？”

客户

“查找客户 John Smith” “提供客户 456 的财务摘要” “搜索有未结余额的客户”

报告（高级版）

“显示本季度的损益表” “打开资产负债表” “我们本月的现金流情况如何？” “显示应收账款账龄报告” “哪些客户付款最慢？”

写入操作（高级版）

“为客户 123 创建发票：网站设计 $2,500，托管 $150/月，账期净 30 天” “记录一笔支付发票 #1042 的 $1,000 支票付款” “记录 3 月 15 日使用信用卡支付给 Office Depot 的一笔 $250 办公用品支出”

分析（高级版）

“我们的财务状况有多健康？显示关键比率” “比较本月和上月” “本季度与去年同期相比如何？”

---

配置

所有配置均通过环境变量完成：

变量	必填	默认值	描述
QBO_CLIENT_ID	是		QuickBooks OAuth2 客户端 ID
QBO_CLIENT_SECRET	是		QuickBooks OAuth2 客户端密钥
QBO_REALM_ID	是		QuickBooks 公司/Realm ID
QBO_REDIRECT_URI	否	http://localhost:8080/callback	OAuth 重定向 URI
LICENSE_KEY	否		高级版许可证密钥
QBO_SANDBOX	否	false	使用沙盒环境
TOKEN_STORE_PATH	否	~/.quickbooks-mcp/tokens.json	令牌存储位置
LOG_LEVEL	否	INFO	日志级别

---

安全性

• 令牌静态加密，使用特定于机器的密钥（Fernet + PBKDF2）
• 令牌自动刷新——访问令牌有效期为 60 分钟，刷新令牌有效期为 100 天
• 代码中不存储凭据——所有机密均通过环境变量提供
• 内置速率限制，以遵守 QuickBooks API 的速率限制
• 对所有查询参数进行输入清理，以防止注入攻击

---

开发

# Clone and install with dev dependencies
git clone https://github.com/nyxtools/quickbooks-mcp-server.git
cd quickbooks-mcp-server
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=quickbooks_mcp

# Lint
ruff check src/ tests/

# Type check
mypy src/

项目结构

quickbooks-mcp-server/
  src/quickbooks_mcp/
    auth/          # OAuth2 flow and encrypted token storage
    client/        # QBO REST API client with rate limiting
    tools/         # MCP tool implementations (19 tools)
    utils/         # Money (Decimal), formatting, license validation
    server.py      # MCP server setup and tool registration
    config.py      # Environment-based configuration
  scripts/
    setup_oauth.py # Interactive OAuth setup
  examples/        # Config examples and usage guide
  tests/           # Pytest test suite

---

故障排除

“未找到 QuickBooks 令牌”

运行 OAuth 设置：

python scripts/setup_oauth.py

“令牌刷新失败”

你的刷新令牌可能已过期。请重新运行 OAuth 设置。

“QuickBooks API 错误（HTTP 403）”

确认你的应用具有 com.intuit.quickbooks.accounting 范围。

“受到 QuickBooks 的速率限制”

服务会自动处理速率限制。如果看到此错误，请等待 60 秒。

“这是高级版功能”

部分工具需要许可证密钥。点击此处获取，或在环境中设置 LICENSE_KEY。

沙盒模式

如需在不影响真实数据的情况下进行测试：

export QBO_SANDBOX=true

请使用 Intuit 开发者控制面板中的开发密钥（而非生产密钥）。

---

许可证

MIT 许可证。详情请参阅 LICENSE。

版权所有 (c) 2026 NyxTools