内容
# qbo-mcp
本地优先的QuickBooks在线MCP服务器。作为一个一键式Claude Desktop扩展（`.mcpb`）提供，非工程师用户可以在大约两分钟内将其账簿连接到Claude。
令牌存储在用户机器上的 `~/.quickbooks-mcp/credentials.json`。无需运行服务器，无需Docker，无需反向代理。
> 查看 [`docs/USER-GUIDE.md`](./docs/USER-GUIDE.md) 以了解Claude连接后可以执行的操作 - 报告、查询、创建/编辑交易，以及不支持的操作。
---
## 安装
### 1. 下载扩展
从[发布页面](https://github.com/matpb/qbo-mcp/releases)获取最新的 `qbo-mcp.mcpb`。
### 2. 注册Intuit开发者应用
您需要自己的Intuit应用来授权访问您的账簿。Claude永远不会看到您的Intuit密码 - 该应用只是Intuit用来识别请求者的方式。
1. 在[developer.intuit.com](https://developer.intuit.com)登录。
2. **仪表板 → 创建应用 → QuickBooks Online 和 Payments**。
3. 命名它（例如`Claude MCP`）并创建。
4. **密钥和凭证 → 生产**（或Sandbox，如果您正在测试）。
5. 在**重定向URI**下，添加：
```
https://qbo-mcp.matpb.com/callback.html
```
保存。这是一个静态的跳转页面，用于将OAuth代码返回到您的本地机器。它不存储任何内容 - 令牌永远不会离开您的笔记本电脑。
6. 从此页面复制**客户端ID**和**客户端密钥**；您将在下一步中使用它们。
### 3. 安装到Claude Desktop
双击 `qbo-mcp.mcpb`。Claude Desktop打开安装提示，询问：
- **Intuit客户端ID** - 来自步骤2。
- **Intuit客户端密钥** - 来自步骤2。
- **使用Intuit Sandbox** - 保留关闭以使用真实账簿；打开以使用Sandbox数据。
安装。QuickBooks扩展现在已启用。
### 4. 授权
在Claude Desktop聊天中，运行：
> 连接我到QuickBooks。
Claude调用 `qbo_authenticate` 工具，该工具：
1. 打开浏览器到Intuit的同意页面。
2. 您登录并选择要连接的公司。
3. Intuit通过 `qbo-mcp.matpb.com/callback.html` 重定向，这将代码跳转回扩展中的临时 `127.0.0.1` 监听器。
4. 扩展将代码交换为访问和刷新令牌，并将其保存到 `~/.quickbooks-mcp/credentials.json`。
Claude确认公司ID。完成。
---
## 日常使用
直接询问Claude。它将调用正确的QBO工具。
示例：
- *"提取2026年第一季度的损益表。"*
- *"显示客户58的未付发票。"*
- *"创建一个借记租金$2,000并贷记银行$2,000的会计分录。"*
每个写入工具默认为 `draft=true` 并首先返回预览 - 您在确认 `draft=false` 之前不会修改账簿。
查看 [`docs/USER-GUIDE.md`](./docs/USER-GUIDE.md) 以获取完整的功能列表。
---
## 何时重新授权
- **刷新令牌在100天不活动后过期。** 如果100多天内没有人询问Claude任何QBO相关问题，则下一个调用将失败，出现 `invalid_grant` 错误。只需重新运行授权步骤。
- **在旋转Intuit客户端密钥后。** 所有令牌都将被注销 - 在扩展程序设置中更新密钥，重启扩展程序，然后重新授权。
- **在从QBO断开应用连接后** （QBO → 齿轮 → 应用 → 已连接的应用 → 断开连接）。
---
## 配置
`.mcpb` 安装在Claude Desktop的扩展程序设置中显示三个字段：
| 字段 | 必需 | 备注 |
|---|---|---|
| Intuit客户端ID | 是 | 来自您的Intuit开发者应用 |
| Intuit客户端密钥 | 是 | 来自您的Intuit开发者应用 |
| 使用Intuit Sandbox | 否 | 连接到sandbox测试数据而不是真实账簿 |
凭证文件：`~/.quickbooks-mcp/credentials.json` （在macOS/Linux上）或 `%USERPROFILE%\.quickbooks-mcp\credentials.json` （在Windows上）。删除它以强制干净的重新授权。
---
## 故障排除
### Intuit在授权期间显示"redirect_uri mismatch"
注册的Intuit开发者应用中的重定向URI与 `https://qbo-mcp.matpb.com/callback.html` 不完全匹配。检查是否有尾部斜杠或输入错误。必须在**生产**选项卡中（除非您在扩展程序设置中启用了Sandbox，否则必须在Sandbox密钥下）。
### "Loopback OAuth timed out after 300s"
您关闭了浏览器标签，耗时太长，或者另一个进程占用了临时端口。请重新运行授权。
### MCP工具调用在数周后返回 `401`
刷新令牌已达到100天不活动期，或应用在Intuit侧断开连接。请重新运行授权。
### "Missing Client Credentials"
扩展程序无法找到客户端ID/密钥。在Claude Desktop中，打开QuickBooks扩展程序设置，确认两个字段均已填充，然后重启扩展程序。
### Intuit错误响应看起来很通用
任何QBO侧的错误（400/验证故障等）都会通过MCP工具结果显示Intuit的`Fault.Error[]`消息和代码。 Intuit的一个已知怪癖：在`query`中使用SQL样式双引号（`''`）内部的引号转义返回一个带有空正文的裸400 - 而是在字符串文字中使用反斜杠转义（`\'`）。
---
## 高级：自托管HTTP / Docker
服务器也作为一个长寿命的HTTP服务运行，用于共享或服务器端部署 - 多个Claude客户端命中一个租户，无需人员值守的代理使用等。
```bash
git clone https://github.com/matpb/qbo-mcp && cd qbo-mcp
cp .env.example .env
# 填写QBO_CLIENT_ID，QBO_CLIENT_SECRET，QBO_REDIRECT_URI（您的https回调），QBO_SETUP_TOKEN（随机字符串）
docker compose up -d
# 监听127.0.0.1:8420 — 使用您自己的TLS反向代理进行前端，然后在Intuit应用中注册/qbo/callback URL。
```
反向代理（nginx示例）：
```nginx
server {
listen 443 ssl http2;
server_name qbo.example.com;
ssl_certificate /etc/letsencrypt/live/qbo.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/qbo.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8420;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Host $host;
}
}
```
启动后，访问 `https://qbo.example.com/qbo/connect?token=<QBO_SETUP_TOKEN>` 以完成OAuth。 将您的MCP客户端指向 `https://qbo.example.com/mcp`。 Claude Desktop用户可以通过 `mcp-remote` 进行桥接：
```json
{
"mcpServers": {
"quickbooks": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://qbo.example.com/mcp"]
}
}
}
```
`src/http-server.ts`中存在一个claude.ai自定义连接器路径（OAuth作为代理与DCR + PKCE），但处于关闭状态。启用 `MCP_AUTH_ENABLED=true` 并设置 `MCP_AUTH_*` 环境变量以启用它。
---
## 爆炸半径和恢复
`com.intuit.quickbooks.accounting`范围授予对以下内容的读取+写入访问：
- **读取：**完整的损益表，资产负债表，总账，现金流量，试算平衡表，每个交易，客户列表（带有电子邮件+地址+税务ID），供应商列表，银行余额。
- **写入：**创建/编辑/删除发票，账单，费用，销售凭证，存款，会计分录，供应商积分，客户，供应商。
该范围 **不** 授予：移动资金（无付款范围），工资，银行馈送，税务申报或UI登录。
如果您怀疑 `~/.quickbooks-mcp/credentials.json` 已泄露：
1. 在Intuit开发者仪表板中，旋转客户端密钥（立即注销所有令牌）或从QBO断开应用连接（齿轮→应用→已连接的应用→断开连接）。
2. 检查QBO审计日志中的可疑活动。
3. 删除 `~/.quickbooks-mcp/credentials.json`，更新扩展程序设置中的密钥，重启，重新授权。
---
## 开发
克隆，安装，构建，打包：
```bash
git clone https://github.com/matpb/qbo-mcp && cd qbo-mcp
npm install
npm run build
npx -y @anthropic-ai/mcpb pack # 生成 qbo-mcp.mcpb
```
在stdio模式下运行（Claude Code，本地shell）：
```bash
export QBO_CLIENT_ID=... QBO_CLIENT_SECRET=...
npm start
```
在HTTP模式下运行（模拟容器）：
```bash
export QBO_CLIENT_ID=... QBO_CLIENT_SECRET=...
export QBO_REDIRECT_URI=http://localhost:8080/qbo/callback
export QBO_SETUP_TOKEN=dev-token
export QBO_CREDENTIAL_FILE=./dev-credentials.json
npm run start:http
# http://localhost:8080/qbo/connect?token=dev-token
```
Intuit确实接受`http://localhost`重定向URI - 在开发过程中注册`http://localhost:8080/qbo/callback`到您的Intuit应用中。
---
## 仓库布局
```
qbo-mcp/
├── manifest.json — MCPB bundle manifest (Claude Desktop)
├── src/
│ ├── index.ts — stdio入口点（.mcpb的默认入口点）
│ ├── http-server.ts — 自托管部署的HTTP入口点
│ ├── server.ts — 共享MCP服务器设置
│ ├── credentials/ — OAuth客户端，循环回调流程，凭证存储
│ ├── client/ — node-quickbooks包装器+缓存+ promisify
│ ├── tools/ — MCP工具定义+处理程序
│ ├── reports/ — 报告摘要格式化器
│ ├── query/ — 通用QBO查询层
│ ├── utils/ — 输出模式，货币，文件实用程序
│ └── types/ — 共享TS类型
├── docs/
│ ├── USER-GUIDE.md — 最终用户功能参考
│ ├── callback.html — OAuth跳转页面（GitHub Pages）
│ └── CNAME — qbo-mcp.matpb.com
├── docker-compose.yml — 自托管HTTP部署
├── Dockerfile
└── .env.example
```
---
## 许可证
MIT。 从
[laf-rge/quickbooks-mcp](https://github.com/laf-rge/quickbooks-mcp) 分叉而来 — 上游是底层QBO工具表面的原始出处。
