内容
# QuickBooks 在线 MCP 服务器
自定义 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于连接 Claude 和 QuickBooks Online。它提供了所有 29 种实体类型的完整 **创建 / 获取 / 更新 / 删除 / 搜索** 工具，以及财务报告 — 直接与 Intuit 会计 API 通信。
> 独立项目。位于其自己的文件夹中，与父目录中的 `qbo-integration` 应用独立。
## 🔗 连接多个公司（客户端）
该服务器同时保存 **每个授权的 QuickBooks 公司**。每个客户端只需授权一次，然后可以立即切换 — 无需重新运行授权脚本，也无需重启 Claude 即可更改公司。两个工具来管理此功能：
- `list_companies` — 查看每个连接的客户端和当前活跃的客户端。
- `set_active_company` — 切换活跃的客户端（按 realmId 或名称）。
每个工具还接受一个可选的 `company` 参数，以针对单个调用的客户端。**新来者？请遵循 [MULTI-COMPANY.md](MULTI-COMPANY.md) 获取完整的逐步设置指南。**
## 您将获得
总共 129 个工具：每个实体的 CRUD + 搜索（与下面的矩阵完全匹配），以及一个 `get_report` 工具，涵盖损益表、资产负债表、现金流量表、试算平衡表、总账、应收/应付账款余额、客户/供应商余额等。
| 实体 | 创建 | 获取 | 更新 | 删除 | 搜索 |
|---|:--:|:--:|:--:|:--:|:--:|
| 客户，发票，估算，账单，供应商，员工 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 项目，记账凭证，账单付款，采购，付款 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 销售凭证，信用备忘录，退款凭证，采购订单 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 供应商信用，存款，转账，时间活动，附件 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 账户，类别，部门，期限，付款方式 | ✅ | ✅ | ✅ | — | ✅ |
| 税码，税率，税务机构 | — | ✅ | — | — | ✅ |
| 公司信息 | — | ✅ | ✅ | — | — |
工具名称遵循可预测的模式：`create_customer`、`get_invoice`、`update_bill`、`delete_estimate`、`search_vendors`、`get_company_info`、`get_report` 等。
## 先决条件
- **Node.js 18 或更高版本**（使用内置的 `fetch`）。
- 一个 **Intuit 开发者账户** 和一个应用 — 在 https://developer.intuit.com 上免费注册。
- 一个要连接的 QuickBooks 公司（一个免费的**沙盒**公司会自动与您的开发者账户一起创建；在使用真实公司之前，请先使用该公司进行测试）。
## 设置
### 1. 创建您的 Intuit 应用
1. 前往 https://developer.intuit.com → **我的应用** → **创建应用** → 选择 **会计** 范围。
2. 打开 **密钥和凭证**。复制 **客户端 ID** 和 **客户端密钥**（分别为开发/沙盒和生产环境准备了一对单独的密钥）。
3. 在 **重定向 URI** 下，添加以下内容：
```
http://localhost:3000/callback
```
### 2. 配置凭证
从此 `quickbooks-mcp-server` 文件夹：
```bash
npm install
cp .env.example .env # 在 Windows 上：copy .env.example .env
```
打开 `.env` 并填写 `QB_CLIENT_ID` 和 `QB_CLIENT_SECRET`。在测试期间，将 `QB_ENVIRONMENT=sandbox` 留空；当您准备好使用真实公司时，切换到 `production`（并使用生产密钥）。
### 3. 授权（一次性）
```bash
npm run auth
```
打开打印的 `http://localhost:3000/` 网址，登录并批准。这会写入一个包含访问令牌、刷新令牌和您的公司的 `realmId` 的 `tokens.json` 文件。然后，服务器会自动刷新访问令牌，因此您只需执行此操作一次（如果您切换公司或刷新令牌在约 100 天的不活动后过期，请重新运行）。
### 4. 将其作为自定义连接器添加到 Claude
在 **Claude Desktop** 中，打开设置 → 开发者 → 编辑配置（`claude_desktop_config.json`）并添加：
```json
{
"mcpServers": {
"quickbooks": {
"command": "node",
"args": ["C:\\Users\\leahs\\OneDrive\\Documents\\Connecting Claude and Quickbooks\\quickbooks-mcp-server\\src\\index.js"]
}
}
}
```
重启 Claude。QuickBooks 工具将出现。（服务器会自动从此文件夹读取 `.env` 和 `tokens.json`。）
## 使用说明
- **创建 / 更新** 使用原生 QuickBooks 字段名称。例如 `create_customer` `data`：`{"DisplayName": "Acme Co", "PrimaryEmailAddr": {"Address": "ap@acme.com"}}`。
- **更新默认替换全部**。要更改少数字段，请在 `data` 中包含 `"sparse": true` 以及 `Id`。如果省略，服务器为您获取当前的 `SyncToken`。
- **删除** 只需要 `id`；`SyncToken` 自动获取。
- **搜索** 在 `where` 字段中使用 QuickBooks 查询语法，例如 `search_invoices` 使用 `where: "TotalAmt > 500 AND Balance > 0"`，或 `search_customers` 使用 `where: "DisplayName LIKE '%Acme%'"`。使用 `limit`/`offset` 进行分页（QBO 每次调用最多返回 1000 个结果）。您也可以传递一个完整的 `query` 字符串。
- **报告**：`get_report` 使用 `report_name`（例如 `ProfitAndLoss`）和 `params`，例如 `{"start_date":"2026-01-01","end_date":"2026-03-31","accounting_method":"Accrual"}`。
## 上线：从沙盒切换到生产环境
服务器设计为可针对任一环境运行 — 上线主要是配置，而不是代码更改。差异：
**1. 切换环境标志。** 在 `.env` 中设置：
```
QB_ENVIRONMENT=production
```
这会自动将请求路由到实时 API (`quickbooks.api.intuit.com`) 而不是沙盒主机。不需要代码编辑。
**2. 使用生产密钥。** Intuit 为生产环境颁发了 **单独** 的客户端 ID / 密钥。在“密钥和凭证”页面上，从 **生产** 部分复制密钥（而不是开发环境），然后输入到 `.env` 中。生产密钥是 gated 的：Intuit 只在您完成应用配置文件（应用名称、EULA 网址、隐私政策网址、主机域名、请求的范围）并通过审核后才会发布它们。在 developer.intuit.com 上完成此操作，然后再等待生产密钥出现。
**3. 注意重定向 URI 规则。** 对于生产环境，Intuit 通常要求重定向 URI 为 **HTTPS** — 用于沙盒的纯 `http://localhost:3000/callback` 可能被拒绝。注册 HTTPS 重定向 URI 并设置 `QB_REDIRECT_URI` 以匹配，或者通过临时安全隧道运行一次性授权。确认您应用设置中的当前要求。
**4. 重新授权。** 令牌特定于环境，因此沙盒 `tokens.json` 将无法对抗真实公司。使用生产密钥运行 `npm run auth` 一次，登录到 **真实** QuickBooks 公司，并写入新的 `tokens.json`（带有真实的 `realmId`）。
**⚠️ 每个操作都是真实的。** 在生产环境中，`create_*`、`update_*` 和 `delete_*` 会更改实际的账簿 — 错误的调用可能会修改或删除真实的财务记录。在上线之前，请考虑在只读模式（仅获取/搜索/报告）下运行或在进行任何写入之前要求明确确认。请始终在沙盒中测试更改。
## 验证配置
```bash
npm run check
```
列出每个工具并确认实体矩阵与需求表匹配。不需要凭证。
## 文件
- `src/index.js` — MCP 服务器；注册所有工具（包括 `list_companies` / `set_active_company`）。
- `src/config.js` — 实体矩阵和报告列表（在此编辑以添加/删除实体）。
- `src/qbClient.js` — OAuth 令牌刷新 + REST 帮助程序 + 多公司令牌存储。
- `auth-production.js` — 授权公司（沙盒或生产环境）；累加，将每个客户端添加到 `tokens.json`。
- `auth.js` — 本地/沙盒专属授权流程（请使用 `auth-production.js` 进行生产环境）。
- `scripts/sanity.js` — 离线配置检查。
- `MULTI-COMPANY.md` — 连接多个客户端的逐步指南。
- `README-PRODUCTION-FIX.md` — 修复“仍显示沙盒公司”的生产授权问题。
## 故障排除
- **"未找到令牌"** — 运行 `npm run auth`。
- **401 / 令牌错误** — 您的刷新令牌可能已过期或您已切换环境；请重新运行 `npm run auth`。
- **"重定向 URI 不匹配"** — 您的 Intuit 应用中的 URI 必须与 `QB_REDIRECT_URI` 完全匹配。
- **沙盒中搜索结果为空** — 沙盒公司一开始几乎是空的；请先创建一个记录或指向一个真实公司。
## 安全
`.env` 和 `tokens.json` 包含机密信息，并被 git 忽略。请将它们保持在共享/版本控制位置之外。这些工具在指向生产公司时可以修改和删除实际会计数据 — 请先在沙盒中测试。
