内容
<div align="center">
# 快速账簿在线 MCP 服务器
一个本地的模型上下文协议（MCP）服务器，暴露快速账簿在线数据和操作，作为可调用的工具，供 MCP 兼容的 AI 助手使用。
</div>
## 📌 概述
快速账簿在线 MCP 服务器为处理快速账簿在线数据提供了一个标准的 MCP 接口。它作为一个 stdio 子进程在本地运行，并通过 Intuit OAuth 2.0 向快速账簿在线公司进行身份验证。
该服务器设计用于 AI 辅助工作流程，其中 MCP 兼容的客户端需要读取或管理快速账簿在线实体，搜索会计记录，或通过结构化工具检索财务报告。
## ✨ 功能
- 快速账簿在线的 MCP 服务器
- 与 Intuit 的 OAuth 2.0 身份验证
- 支持沙盒和生产快速账簿在线环境
- 适用于客户、发票、账单、供应商、付款、账户、项目等的快速账簿在线实体工具
- 包括资产负债表、利润和亏损、现金流、试算平衡表和总账在内的财务报告工具
- 可选的环境标志，用于禁用写入、更新或删除工具类别
- 使用 Zod 验证的 TypeScript 实现
- 由上游文档引用的 Jest 测试套件
## 🧰 工具覆盖
服务器通过 MCP 工具公开快速账簿在线功能。
### 实体
支持的实体类别包括：
- 客户
- 发票
- 估算单
- 账单
- 供应商
- 员工
- 账户
- 项目
- 日记账分录
- 账单付款
- 采购
- 付款
- 销售收款
- 信用备忘录
- 退款收款
- 采购订单
- 供应商信用
- 存款
- 转账
- 时间活动
- 分类
- 部门
- 条款
- 付款方式
- 税码
- 税率
- 税务机构
- 公司信息
- 可附着
大多数实体支持创建、获取、更新、删除和搜索操作，快速账簿在线支持这些操作。某些实体是只读的或不支持删除。
### 报告
可用的报告工具包括：
| 报告 | 工具 |
|---|---|
| 资产负债表 | `get_balance_sheet` |
| 利润和亏损 | `get_profit_and_loss` |
| 现金流 | `get_cash_flow` |
| 试算平衡表 | `get_trial_balance` |
| 总账 | `get_general_ledger` |
| 客户销售 | `get_customer_sales` |
| 应收账款账龄 | `get_aged_receivables` |
| 应收账款账龄详情 | `get_aged_receivables_detail` |
| 客户余额 | `get_customer_balance` |
| 应付账款账龄 | `get_aged_payables` |
| 供应商支出 | `get_vendor_expenses` |
## 🔐 身份验证
此服务器使用 Intuit OAuth 2.0。要将其连接到快速账簿在线，您需要在 Intuit 开发者门户中创建一个应用，并完成 OAuth 授权流程。
所需的环境值包括：
```env
QUICKBOOKS_CLIENT_ID=您的客户端 ID
QUICKBOOKS_CLIENT_SECRET=您的客户端密钥
QUICKBOOKS_ENVIRONMENT=沙盒
QUICKBOOKS_REFRESH_TOKEN=您的刷新令牌
QUICKBOOKS_REALM_ID=您的领域 ID
```
可选标志可以限制已注册的工具类别：
```env
QUICKBOOKS_DISABLE_WRITE=true
QUICKBOOKS_DISABLE_UPDATE=true
QUICKBOOKS_DISABLE_DELETE=true
```
读取工具（如 `get_*` 和 `search_*`）仍然可用。
### 沙盒和生产说明
- 沙盒使用可以使用本地回调，例如 `http://localhost:8000/callback`。
- 生产 OAuth 设置需要一个公共 HTTPS 重定向 URI 用于初始授权。
- 在初始 OAuth 握手后，服务器使用存储的刷新令牌在本地运行，直到需要重新授权。
## ⚙️ 基本设置
```bash
git clone https://github.com/your-username/mcp-quickbooks-online.git
cd mcp-quickbooks-online
npm install
npm run build
```
从提供的环境模板创建 `.env` 文件并填写快速账簿在线 OAuth 值。
```bash
cp .env.example .env
```
运行上游文档中描述的 OAuth 助手：
```bash
npm run auth
```
## 🤖 MCP 客户端配置
MCP 配置示例：
```json
{
"mcpServers": {
"quickbooks": {
"command": "node",
"args": ["path/to/mcp-quickbooks-online/dist/index.js"],
"env": {
"QUICKBOOKS_CLIENT_ID": "您的客户端 ID",
"QUICKBOOKS_CLIENT_SECRET": "您的客户端密钥",
"QUICKBOOKS_REFRESH_TOKEN": "您的刷新令牌",
"QUICKBOOKS_REALM_ID": "您的领域 ID",
"QUICKBOOKS_ENVIRONMENT": "沙盒",
"QUICKBOOKS_DISABLE_WRITE": "false",
"QUICKBOOKS_DISABLE_UPDATE": "false",
"QUICKBOOKS_DISABLE_DELETE": "false"
}
}
}
}
```
## 🧪 开发
构建项目：
```bash
npm run build
```
运行测试：
```bash
npm test
```
上游 README 引用了一个 Jest 测试套件和 TypeScript 实现。
## 🧭 工具命名
工具名称遵循 `{verb}_{entity}` 约定。
| 前缀 | 类别 | 限制标志 |
|---|---|---|
| `create_` | 写入 | `QUICKBOOKS_DISABLE_WRITE=true` |
| `update_` | 更新 | `QUICKBOOKS_DISABLE_UPDATE=true` |
| `delete_` | 删除 | `QUICKBOOKS_DISABLE_DELETE=true` |
| `get_`、`search_`、`read_` | 读取 | 始终可用 |
## ❓ 常见问题
### 该项目用于什么？
它为快速账簿在线提供了一个 MCP 接口，以便 AI 助手和其他 MCP 兼容的客户端可以以结构化的方式调用与快速账簿相关的工具。
### 它作为托管服务运行吗？
否。文档中描述的行为是作为用户机器上的 stdio 子进程运行的本地 MCP 服务器。
### 是否需要 OAuth？
是的。访问快速账簿在线需要通过在 Intuit 开发者门户中创建的应用进行 Intuit OAuth 2.0。
### 可以禁用写入操作吗？
是的。环境标志可以抑制创建、更新和删除工具，同时保留读取工具可用。
### 它支持报告吗？
是的。文档中的报告工具包括资产负债表、利润和亏损、现金流、试算平衡表、总账、客户报告、应收账款报告、应付账款报告和供应商支出。
## 📄 许可证
MIT 许可证。详情请参见 `LICENSE`。
## 🙏 致谢
该项目基于 Intuit 的快速账簿在线 MCP 服务器，并使用模型上下文协议。
