内容
# QuickBooks Online MCP Server
一个MCP服务器,通过Claude Desktop提供对QuickBooks Online财务数据和报告功能的访问。自然地询问您的财务数据,Claude将帮助分析和解释。
## 特性
- **财务数据访问**
- 获取账户列表 (`get_accounts`)
- 获取客户信息 (`get_customers`)
- 获取最近的发票 (`get_recent_invoices`)
- **财务报告**
- 生成损益表 (`get_profit_loss`)
- 生成资产负债表 (`get_balance_sheet`)
- 获取应收账款报告 (`get_aged_receivables`)
- 使用过滤器搜索交易历史 (`search_transactions`)
- **引导财务分析**
- 分析现金流 (`analyze_cash_flow` 提示)
- 执行每月财务审查 (`monthly_review` 提示)
- 分析应收账款 (`accounts_receivable_analysis` 提示)
## 先决条件
1. 安装 [Claude Desktop](https://claude.ai/download)
2. 安装 Python 3.10 或更高版本
3. 设置 QuickBooks Online:
- 创建一个 [开发者账户](https://developer.intuit.com/)
- 在Intuit开发者门户中创建一个新应用。
- 记下您的 **Client ID** 和 **Client Secret**。
- 配置OAuth **Redirect URI**(此服务器使用的默认值是 `http://localhost:8000/callback`,确保与您的应用设置匹配)。
- 通过OAuth 2.0流程为您的应用获取初始 **Refresh Token**(此服务器需要一个刷新令牌来连接,但不处理初始获取)。
- 知道您的QuickBooks **Company ID**。
## 安装
1. 安装包:
```bash
# 确保您在项目的根目录
pip install .
```
2. 配置凭据:
在您的系统或终端会话中设置以下环境变量:
- `QBO_CLIENT_ID`: 您的QuickBooks应用Client ID。
- `QBO_CLIENT_SECRET`: 您的QuickBooks应用Client Secret。
- `QBO_ENVIRONMENT`: `sandbox` 或 `production`。
- `QBO_REDIRECT_URI`: 在您的应用中配置的重定向URI(例如,`http://localhost:8000/callback`)。
- `QBO_COMPANY_ID`: 您的QuickBooks Company ID。
- `QBO_REFRESH_TOKEN`: 在OAuth设置期间获得的初始刷新令牌。
*或者,如果存在,服务器可以从 `~/.qbo-mcp/token.json` 读取刷新令牌。*
## 与Claude Desktop一起使用
1. 在Claude Desktop中安装服务器:
确保在运行此命令的终端中设置了步骤2中的环境变量。
```bash
mcp install qbo-mcp
```
*或者,如果您不想设置系统范围的环境变量,可以创建一个临时的 `.env` 文件并使用 `-f` 标志:*
```bash
# 示例临时 .env 文件内容:
# QBO_CLIENT_ID=YOUR_ID
# QBO_CLIENT_SECRET=YOUR_SECRET
# ... (其他变量)
mcp install qbo-mcp -f /path/to/your/temporary/.env
```
2. 与Claude开始对话,自然地询问您的财务数据。例如:
- "我们的现金流情况如何?"
- "你能审查一下上个月的财务表现吗?"
- "给我显示逾期应收账款并建议收款策略"
- "我们上个季度的总销售额是多少?"
- "给我显示上个月与客户X的所有交易"
3. 示例对话:
```
你:你能分析一下我们当前的现金流情况吗?
Claude:我将帮助您分析公司的现金流情况。我将:
1. 审查当前的资产负债表以评估现金状况
2. 检查应收账款以了解收款状态
3. 识别任何令人担忧的趋势
4. 提供具体建议
您希望我继续进行此分析吗?
你:是的,请。
[Claude将分析财务数据并提供见解]
```
## 故障排除
常见问题及解决方案:
1. **身份验证错误**
- 检查您的QBO凭据在 `.env` 中
- 尝试使用 `qbo-mcp auth` 重新进行身份验证
- 确保您的OAuth令牌有效
2. **连接问题**
- 验证您的互联网连接
- 检查QBO是否可访问
- 确保您的公司ID正确
3. **Claude Desktop集成**
- 确保Claude Desktop正在运行
- 检查服务器是否正确安装
- 验证环境变量是否已加载
## 开发
1. 创建虚拟环境:
```bash
python -m venv .venv
source .venv/bin/activate # Linux/Mac
.venv\Scripts\activate # Windows
```
2. 安装开发依赖:
```bash
pip install -e ".[dev]"
```
3. 运行测试:
```bash
pytest
```
## 安全
- 所有操作均为只读,以保护财务数据
- 凭据通过环境变量管理
- OAuth令牌安全存储在用户的主目录中
- 访问仅限于授权的QuickBooks公司账户
- 所有API调用均记录以供审计使用
## 许可证
MIT