内容
# bicom-mcp-ai
**连接您的BICOM ERP与AI助手。** 从Claude Desktop或ChatGPT Desktop以自然语言提问关于销售、收款、库存、客户和采购的问题。
```
> 这个月我卖了多少，相比上个月怎么样？
💰 销售总结
期间：2026年5月1日 → 2026年5月26日
- 已发单据：243
- 总毛额：$5,765,217
- 总净额：$4,454,353
- 增值税：$814,951
与上一期间比较 📉
- 变化：-95.4% (-$119,027,516)
- 上一期间：357份单据，$124,792,733
按单据类型划分
| 类型 | 单据数量 | 总金额 |
| --------------------------- | -----: | ----------: |
| 电子发票 | 64 | $2,610,400 |
| 电子收据 | 142 | $2,313,669 |
| 电子信用额度 | 12 | $504,082 |
| 电子发货单| 7 | $184,990 |
| 电子免税发票 | 7 | $96,480 |
| 电子免税收据 | 11 | $55,596 |
```
这就是您在连接MCP后在Claude Desktop上看到的内容。继续阅读，10分钟内即可安装。
---
## 您可以用什么问题来提问
8种工具连接到您的BICOM企业数据库：
| 类别 | 示例 |
|---|---|
| 💰 **销售** | "这个月我卖了多少？", "本季度十大产品", "今年我最好的销售员是谁？" |
| 👥 **客户** | "谁是我的最佳客户？", "本季度前20名客户" |
| 📒 **收款** | "总共欠我多少钱？", "哪些客户已经超过60天没付款？" |
| 📦 **库存** | "哪些产品快要卖完了？", "库存为0的产品" |
| 🛒 **采购** | "今年我花了多少钱在采购上？", "比较本月采购和销售" |
**可用期间**: 今天、昨天、本周、本月、上月、当前季度、今年。所有期间都自动与上一期间比较。
---
## ⚙️ 安装 — Claude Desktop（推荐）
> **预计时间：** 10分钟 · **难度：** 低（不需要编程知识）
### 步骤 1 — 安装 Node.js 和 pnpm
如果您以前从未安装过Node：
- **Mac / Linux**：从 [nodejs.org](https://nodejs.org) 下载（LTS版本，20或更高）。
- **Windows**：从 [nodejs.org](https://nodejs.org) 下载 `.msi` 安装程序，并完成向导步骤。
然后打开终端（在Mac上：`Terminal.app`；在Windows上：`PowerShell` 或 `cmd`）并执行：
```bash
node --version
```
应显示 `v20.x.x` 或更高版本。如果有效，请安装pnpm：
```bash
npm install -g pnpm
```
### 步骤 2 — 下载并编译MCP
在同一终端中，切换到您要保存的目录（通常是 `Documents`），并执行：
```bash
git clone https://github.com/BICOM-OFICIAL/bicom-mcp-ai.git
cd bicom-mcp-ai
pnpm install
pnpm build
```
这将可执行文件留在 `dist/index.js`。**记下该文件的完整绝对路径**，您将在步骤 4 中需要它。
- Mac/Linux：通常为 `/Users/<您的用户名>/bicom-mcp-ai/dist/index.js`
- Windows：通常为 `C:\Users\<您的用户名>\bicom-mcp-ai\dist\index.js`
### 步骤 3 — 获取您的API令牌
向BICOM管理员（或从后台 `/admin/tokens`）请求您的企业的API令牌。您将收到类似以下内容的UUID：
```
79823361-92f1-4799-a234-341c3aa4e07f
```
保存它，您将在步骤 4 中使用它。**请勿分享** — 它像密码一样工作。
### 步骤 4 — 配置Claude Desktop
找到根据您的操作系统确定的配置文件：
| 操作系统 | 位置 |
|---|---|
| **Mac** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Linux** | `~/.config/Claude/claude_desktop_config.json` |
用文本编辑器（TextEdit, Notepad, VS Code等）打开它。如果文件不存在，请使用以下内容创建：
```json
{
"mcpServers": {
"bicom": {
"command": "node",
"args": ["/RUTA/ABSOLUTA/A/bicom-mcp-ai/dist/index.js"],
"env": {
"BICOM_API_TOKEN": "您的uuid令牌",
"BICOM_API_BASE_URL": "https://bicomrest.bicomstore.cl"
}
}
}
}
```
如果已经存在其他配置好的MCP，只需在`mcpServers`中添加`"bicom": { ... }`。
**替换**：
- `/RUTA/ABSOLUTA/A/bicom-mcp-ai/dist/index.js` → 步骤2中文件的实际路径。
- `您的uuid令牌` → 步骤3中获得的实际UUID令牌。
> ⚠️ **Windows**：在路径中使用正斜杠（/），不要使用反斜杠。示例：`"C:/Users/Jose/bicom-mcp-ai/dist/index.js"`。
### 步骤 5 — 重启Claude Desktop
**完全关闭Claude** （右键单击图标 → Quit，而不仅仅是最小化）。重新打开它。
重新打开后，您将在输入栏中看到一个工具图标。单击它，**bicom**及其8种列出的工具应该会出现。
### 步骤 6 — 测试
向Claude查询。一些开始示例：
- *"这个月我在BICOM卖了多少？"*
- *"给我今年的5大客户名单"*
- *"谁是超过30天没付钱的客户？"*
- *"给我一份BICOM本月的执行报告"*
> 💡 **提示**：如果您配置了其他电子发票MCP，请在查询中指定“在BICOM”或“来自我的BICOM公司”，以便Claude不会混淆数据源。
---
## ⚙️ 安装 — ChatGPT Desktop
ChatGPT Desktop通过 **Settings → Apps & Connectors → Developer** 支持MCP。原生集成针对远程服务器（HTTP/SSE）进行了优化。
> **当前状态（V1）**：`bicom-mcp-ai` 使用 **STDIO** 协议（Claude Desktop标准）。要与ChatGPT Desktop一起使用，有两种方法：
### 选项 A — 等待原生SSE支持（V2）
我们正在集成SSE传输，以便ChatGPT Desktop直接支持。**ETA：MCP的V2** （未来几周）。
### 选项 B — 使用STDIO ↔ HTTP桥（高级）
如果您现在需要在ChatGPT上使用它，可以使用 `mcp-remote` 包，它将本地STDIO服务器公开为HTTP/SSE。ChatGPT Desktop的配置将指向 `http://localhost:<port>`，而桥将本地运行：
```bash
npx -y mcp-remote node /RUTA/ABSOLUTA/A/bicom-mcp-ai/dist/index.js --port 7878
```
然后在ChatGPT Desktop → 设置 → 应用程序和连接器 → 添加MCP服务器 → URL `http://localhost:7878`。在启动桥之前，通过环境变量配置令牌：
```bash
export BICOM_API_TOKEN="您的uuid令牌"
export BICOM_API_BASE_URL="https://bicomrest.bicomstore.cl"
```
> 💡 **推荐**：目前使用Claude Desktop — 它是ChatGPT Desktop支持STDIO或我们发布SSE版本之前的更稳定体验。
---
## 🧠 组合查询
Claude可以在单个查询中运行多个工具。一些示例：
| 查询 | Claude执行的操作 |
|---|---|
| *"给我一份BICOM本月的执行报告"* | 销售 + 顶级产品 + 顶级客户 + 应收账款 + 警报 |
| *"我的业务怎么样？"* | 销售 + 应收账款 + 低库存 → 60秒内健康检查 |
| *"哪些客户是顶级客户但也欠我钱？"* | 顶级客户 + 逾期客户，交叉 |
| *"比较我的盈利能力：今年的销售 vs 采购"* | 销售总结 + 采购总结，今年 |
---
## 🐛 故障排除
### "bicom" 未出现在MCP列表中
1. **完全关闭** Claude Desktop（系统托盘 → Quit，而不仅仅是最小化）。
2. 检查配置文件中的路径 — 必须是**绝对路径**，而不是相对路径。
3. 在Windows上，在路径中使用 `/` 而不是 `\`。
4. 检查 `dist/index.js` 是否存在（如果不存在，请再次运行 `pnpm build`）。
### Claude 回答 "api_token 无效"
令牌已过期或被停用。向管理员请求一个新的令牌，并更新 `BICOM_API_TOKEN` 配置。重启Claude Desktop。
### Claude 回答 "此公司未启用收款"
您的公司使用旧的金库模型（`new_treasury=0`）。在这种情况下，不适用应收账款和坏账报告 — 但**其他工具正常工作**。支持该模式的计划在V2中。
### 意外的错误或无响应
检查Claude Desktop的日志文件：
| 操作系统 | 位置 |
|---|---|
| Mac | `~/Library/Logs/Claude/mcp-server-bicom.log` |
| Windows | `%APPDATA%\Claude\logs\mcp-server-bicom.log` |
将内容发送给BICOM管理员或在此存储库中打开一个问题。
---
## 🛡️ 安全
- `BICOM_API_TOKEN` **明文** 存储在 `claude_desktop_config.json` 中。将该文件视为密码。
- MCP **仅读取** 您公司的数据 — 无法创建、修改或删除任何内容。
- 每个令牌都 **限定范围为您的公司**：您永远无法使用您的令牌查看其他公司的数据，反之亦然。
- 与 `bicomrest.bicomstore.cl` 的所有通信都通过 **HTTPS** 进行。
---
## 📚 资源
- **BICOM API 后端**：存储库 `bicom-api-go` （私有）中的内部文档。
- **此MCP使用的端点**：`/api/stats/*` （8个REST端点）。
- **MCP协议**： [modelcontextprotocol.io](https://modelcontextprotocol.io) — Claude使用的标准。
## 📄 许可证
MIT — 查看 [LICENSE](LICENSE)。
