内容
# qbo-mcp
[](https://github.com/SrishtiKalpa/accouting-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://pypi.org/project/qbo-mcp/)
[](https://hub.docker.com/r/srishtikalpa/qbo-mcp)
开源的MCP服务器，连接AI助手（如Claude、Cursor、Windsurf等）到QuickBooks在线版。您可以向会计系统提问，创建发票，运行报告等，并内置了人工审核的安全层。
## 这是什么？
`qbo-mcp`实现了[模型上下文协议](https://modelcontextprotocol.io)，为AI助手提供直接、安全地访问QuickBooks在线版数据的能力。所有写操作都经过草稿和确认的工作流程——AI提出更改，您来确认。
## 快速开始 — Docker（30秒）
```yaml
# docker-compose.yml
services:
qbo-mcp:
image: srishtikalpa/qbo-mcp:latest
ports: ["8000:8000"]
environment:
QBO_CLIENT_ID: 您的客户端ID
QBO_CLIENT_SECRET: 您的客户端密钥
QBO_ENVIRONMENT: 沙盒环境
```
```bash
# 1. 克隆
git clone https://github.com/yourusername/qbo-mcp && cd qbo-mcp
# 2. 配置
cp .env.example .env # 填写QBO_CLIENT_ID、QBO_CLIENT_SECRET
# 3. 启动
docker compose up
# 4. 连接公司（在Claude中）
# 提问: "连接我的QuickBooks公司，realm ID为9341453472467123"
# 5. 提问
# "显示我所有逾期的发票"
# "2025年第一季度的净利润是多少？"
```
## 快速开始 — Claude Desktop（stdio）
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"quickbooks": {
"command": "uvx",
"args": ["qbo-mcp"],
"env": {
"MCP_TRANSPORT": "stdio",
"QBO_CLIENT_ID": "您的客户端ID",
"QBO_CLIENT_SECRET": "您的客户端密钥",
"QBO_ENVIRONMENT": "沙盒环境"
}
}
}
}
```
或直接运行：`uvx qbo-mcp`
## 连接您的第一个公司
1. 从[developer.intuit.com](https://developer.intuit.com)获取凭证——创建应用，记录客户端ID和密钥
2. 在QuickBooks在线版URL中找到Realm ID：`qbo.intuit.com/app/homepage?realmId=XXXXXXX`
3. 告诉Claude：_"连接我的QuickBooks公司 'Acme Corp'，realm ID为XXXXXXX"_
4. Claude返回Intuit OAuth URL——打开，登录并授权
5. 从回调中复制`code`和`state`，告诉Claude执行`complete_oauth_connection`
6. 完成——提问关于您的账簿
## 安全模型
每个写操作（创建、更新、作废、发送）都经过三步流程：
1. **草稿** —— Claude提出更改并返回`draft_action_id`
2. **预览** —— 调用`preview_action`查看将发送到QuickBooks的内容
3. **提交或取消** —— 调用`commit_action`执行或`discard_action`取消
额外防护：
- **只读模式** —— 按公司设置的标志，阻止所有写操作
- **美元阈值** —— 按公司设置的阈值，阻止超过指定金额的写操作
- **审计日志** —— 每个工具调用都记录到SQLite数据库中，包含结果和草稿ID
## 工具参考
查看 [docs/TOOLS.md](docs/TOOLS.md) 获取全部30+工具的列表。
亮点：
- **CRUD**：发票、客户、供应商、账单、账户
- **报告**：损益表、资产负债表、现金流量表、应收/应付账款老龄分析表、试算平衡表
- **智能分析**：重复检测、月末检查清单、异常检测、健康总结
## 配置
| 变量 | 默认值 | 描述 |
|---|---|---|
| `MCP_TRANSPORT` | `stdio` | `stdio` 或 `streamable-http` |
| `MCP_PORT` | `8000` | HTTP服务器端口 |
| `QBO_CLIENT_ID` | — | Intuit应用客户端ID（必填） |
| `QBO_CLIENT_SECRET` | — | Intuit应用客户端密钥（必填） |
| `QBO_ENVIRONMENT` | `sandbox` | `sandbox` 或 `production` |
| `QBO_REDIRECT_URI` | `http://localhost:8000/oauth/callback` | OAuth回调URL |
| `DB_PATH` | `./accounting.db` | SQLite数据库路径 |
| `DEFAULT_DRAFT_MODE` | `true` | 所有写操作先进入草稿模式 |
| `LOG_LEVEL` | `INFO` | 日志级别 |
## 贡献
```bash
git clone https://github.com/yourusername/qbo-mcp
cd qbo-mcp
uv sync --extra dev
cp .env.example .env
uv run pytest
```
欢迎提交PR。请在提交前运行 `uv run ruff check` 和 `uv run mypy src/`。
## 许可证
MIT — 查看 [LICENSE](LICENSE)。
