AI导哈

QuickBooks在线MCP服务器

提供6个参数化工具，覆盖账户、客户、供应商、员工、交易（13种类型）、项目、参考数据和11种财务报告的约120种操作。

  • by hvkshetry
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 hvkshetry/quickbooks-mcp

使用说明

快速书籍mcp

QuickBooks Online的MCP服务器——6个参数化工具，涵盖账户、客户、供应商、员工、交易（13种类型）、项目、参考数据和11份财务报告中的约120项操作。

建于 FastMCP 和 python快速书籍设计用于 克劳德代码 以及其他MCP兼容客户端。

工具

工具 操作 盖子
account 列表、获取、创建、更新、停用、搜索 科目表管理
party 列表、获取、创建、更新、停用、搜索 客户、供应商、员工(party_type 参数）
transaction 列表、获取、创建、更新、删除、作废、搜索 13种类型：发票、账单、账单支付、付款、存款、转账、日记账尝试、购买、估算、信用管理、销售接收、退款接收、供应商信用
item 列表、获取、创建、更新、停用、搜索 产品和服务
reference list_tax_codes、list_classes、list_departments、list_tterms、list_payment_methods、get_company_info、get_references 查找数据和公司设置
report 损益表、余额表、试算表、现金流、总账、ar_aging_summary、ar_agin_detail、ap_aging_ssummary、ap_agin_detail、客户余额、供应商平衡 带日期范围和过滤器参数的财务报告

先决条件

设置

1.克隆和配置

git clone https://github.com/hvkshetry/quickbooks-mcp.git
cd quickbooks-mcp
cp .env.example .env

编辑 .env 使用您的Intuit应用程序凭据：

QBO_CLIENT_ID=<from Intuit Developer Portal>
QBO_CLIENT_SECRET=<from Intuit Developer Portal>
QBO_ENVIRONMENT=production
QBO_REDIRECT_URI=http://localhost:8010/callback

2.注册重定向URI

在 Intuit开发者门户:

  1. 打开你的应用程序→ 钥匙和凭证
  2. 在...之下 重定向URI，添加： http://localhost:8010/callback

生产说明： Intuit需要HTTPS重定向URI作为生产密钥。对于本地开发，请使用您的development密钥（允许HTTP localhost）。或者，使用类似隧道的 云层爆发 要通过HTTPS公开localhost，请将隧道URL注册为重定向URI，并设置 QBO_REDIRECT_URI 因此。

3.授权

uv run python auth_flow.py

这将打开您的浏览器到Intuit的OAuth页面。登录，选择您的QuickBooks公司，然后授权。剧本写道 QBO_REFRESH_TOKEN 和 QBO_REALM_ID 到 .env 自动。

4.运行服务器

uv run python server.py        # STDIO transport (default)
uv run python server.py sse    # SSE transport on port 8020

MCP客户端配置

克劳德代码

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "quickbooks-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/quickbooks-mcp", "run", "python", "server.py"]
    }
  }
}

其他MCP客户端

任何兼容MCP的客户端都可以通过STDIO或SSE传输进行连接。看 MCP规范 了解详情。

使用示例

列出账户

account(operation="list", limit=10, account_type="Expense")

搜索供应商

party(operation="search", party_type="vendor", query="Acme")

创建发票

transaction(operation="create", entity_type="invoice", data={
  "CustomerRef": {"value": "42"},
  "TxnDate": "2025-01-15",
  "DueDate": "2025-02-14",
  "Line": [{
    "Amount": 500.00,
    "DetailType": "SalesItemLineDetail",
    "SalesItemLineDetail": {
      "ItemRef": {"value": "1"},
      "Qty": 10,
      "UnitPrice": 50.00
    }
  }]
})

创建日记条目

transaction(operation="create", entity_type="journal_entry", data={
  "TxnDate": "2025-01-31",
  "PrivateNote": "Accrue January utilities",
  "Line": [
    {
      "Amount": 2500.00,
      "DetailType": "JournalEntryLineDetail",
      "JournalEntryLineDetail": {
        "PostingType": "Debit",
        "AccountRef": {"value": "62"}
      }
    },
    {
      "Amount": 2500.00,
      "DetailType": "JournalEntryLineDetail",
      "JournalEntryLineDetail": {
        "PostingType": "Credit",
        "AccountRef": {"value": "45"}
      }
    }
  ]
})

运行损益报告

report(operation="profit_and_loss", start_date="2025-01-01", end_date="2025-12-31")

让AR老化

report(operation="ar_aging_summary", end_date="2025-12-31")

关键模式

创建前搜索 --在创建之前始终搜索现有实体，以避免重复：

account(operation="search", query="Utilities")
# If not found, then create

更新前获取 --QBO需要电流 SyncToken 以获取更新。客户端通过在应用更改之前获取实体来自动处理此问题：

transaction(operation="get", entity_type="bill", entity_id=123)
transaction(operation="update", entity_type="bill", entity_id=123, data={...})

令牌刷新 --服务器会自动刷新过期的OAuth令牌，并将新的刷新令牌持久化到 .env。如果身份验证持续失败，请重新运行 uv run python auth_flow.py.

建筑

quickbooks-mcp/
├── server.py       # FastMCP server — 6 tools with @mcp.tool decorators
├── client.py       # QBOClient wrapper — async safety, token refresh, rate limiting
├── auth_flow.py    # One-time OAuth flow (port 8010)
├── pyproject.toml  # Dependencies: python-quickbooks, intuit-oauth, mcp, dotenv
├── .env.example    # Environment variable template
└── .env            # Your credentials (git-ignored)
  • 全部 python-quickbooks 通话被包裹在 asyncio.to_thread() 异步安全
  • 令牌刷新已锁定(asyncio.Lock)防止并发刷新竞争
  • 速率限制：HTTP 429上的自动指数回退（QBO限制：500请求/分钟，10请求/秒）
  • 令牌持久化：原子写入 .env 通过临时文件+ os.replace()

许可证

麻省理工学院

相关 MCP