Kingdee K3Cloud MCP
README.md
# Kingdee K3Cloud MCP
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
面向 **金蝶云星空(K3Cloud)** 的企业级 **MCP 服务端** + 配套 **Agent Skill**。
- **服务端**:一个容器,客户填好环境变量即可运行,向 AI 暴露 17 个 ERP 工具。
- **Skill**:一份技能包,导入支持 Skill 机制的 Agent(WorkBuddy、Claude Code、千问办公等)即可获得表单字段与业务工作流知识。
> 两者可独立使用:只用 MCP 也有完整工具;叠加 Skill 后 Agent 更少踩坑。
---
## 目录
- [特性](#特性)
- [快速开始](#快速开始)
- [客户端接入](#客户端接入)
- [Skill 导入](#skill-导入)
- [工具清单](#工具清单)
- [安全模型](#安全模型)
- [上线前联调](#上线前联调)
- [项目结构](#项目结构)
- [开发](#开发)
详细文档:
| 文档 | 内容 |
|---|---|
| [docs/deploy.md](docs/deploy.md) | 服务端部署(Docker / 离线内网 / Python / 传输模式 / 升级) |
| [docs/client-setup.md](docs/client-setup.md) | 客户端配置(WorkBuddy / Claude / Cursor / Cline / 千问办公等) |
| [docs/skill-import.md](docs/skill-import.md) | Skill 导入(各 Agent 目录与打包方式) |
---
## 特性
- **开箱即用**:环境变量配好即跑,无需手改配置文件、无需编译。
- **只读 / 读写双模式**:只读模式下 7 个写工具**物理不存在**,从工具层防误写。
- **大数据友好**:自动翻页、按日期分片、流式落盘(ndjson / csv),规避 2000 行与 1MB 限制。
- **结构化审计**:每次调用记录 who / tool / 参数 / 耗时 / 结果,密钥字段自动脱敏。
- **可操作错误**:金蝶原始报错归类为认证 / 权限 / 会话 / 不存在,并附修复建议。
- **生产级容器**:非 root、只读根文件系统、`cap_drop: ALL`、内置健康检查。
---
## 快速开始
### 1. 准备金蝶凭据
在金蝶云星空后台:**系统管理 → 第三方系统登录授权**,新增集成用户并获取:
`KD_SERVER_URL`、`KD_ACCT_ID`、`KD_USERNAME`、`KD_APP_ID`、`KD_APP_SEC`
> 建议为 MCP 单独建一个集成用户,只授予必要权限,不要用 administrator。
### 2. 启动服务
```bash
git clone https://github.com/tonyw5186-cell/kingdee-k3cloud-mcp-and-skill.git
cd kingdee-k3cloud-mcp-and-skill
cp .env.example .env
# 编辑 .env,填入上面 5 个值(默认 MCP_MODE=readonly)
docker compose up -d --build
docker compose logs -f
```
看到 `MCP Server running` 即启动成功,默认监听 `:8000`,SSE 地址 `http://<host>:8000/sse`。
### 3. 接入客户端
把下面配置贴进支持 MCP 的客户端(以 SSE 为例):
```json
{
"mcpServers": {
"kingdee-k3cloud": {
"url": "http://<host>:8000/sse",
"type": "sse"
}
}
}
```
接入后调用 `ping`,返回 `{"ok": true, ...}` 即成功。各客户端详细位置见 [docs/client-setup.md](docs/client-setup.md)。
---
## 客户端接入
服务端支持三种传输,按客户端能力选择:
| 传输 | 地址 | 适用 |
|---|---|---|
| **SSE**(默认) | `http://<host>:8000/sse` | 大多数远程 MCP 客户端 |
| **Streamable HTTP** | `http://<host>:8000/mcp` | 新式客户端(`MCP_TRANSPORT=streamable-http`) |
| **stdio** | 本地进程 | 不支持远程、但支持 stdio 的客户端 |
| 客户端 | 推荐传输 | 配置位置(以各版本为准) |
|---|---|---|
| **WorkBuddy** | SSE | 连接器 / MCP 设置,粘贴 JSON |
| **Claude Code** | SSE 或 stdio | 项目 `.mcp.json` 或 `~/.claude/settings.json` |
| **Claude Desktop** | stdio | `claude_desktop_config.json` |
| **Cursor** | SSE 或 stdio | `~/.cursor/mcp.json` 或 Settings → MCP |
| **Cline / Continue** | SSE 或 stdio | 扩展的 MCP 配置面板 |
| **Cherry Studio** | SSE | 设置 → MCP 服务器 |
| **千问办公 / 其他** | SSE | MCP / 工具扩展设置,粘贴标准 JSON |
完整示例与排错见 [docs/client-setup.md](docs/client-setup.md)。
---
## Skill 导入
Skill 是**知识包**,不是连接器:它告诉 Agent 用哪个表单、哪个字段、怎么查,实际执行仍由 MCP 完成。
| Agent | Skill 机制 | 导入方式 |
|---|---|---|
| **WorkBuddy** | ✅ | 复制到 `~/.workbuddy/skills/kingdee-k3cloud/` |
| **Claude Code** | ✅ | 复制到 `~/.claude/skills/kingdee-k3cloud/` |
| **千问办公** | ✅(按版本) | 技能 / 插件导入入口,选择目录或技能包 |
| **其他支持 Skills 的 Agent** | ✅ | 放入其 skills 目录,或导入打包后的 zip |
| **仅支持 MCP 的客户端** | ❌ | 直接用 MCP 的 17 个工具,不影响功能 |
```bash
# 方式一:直接复制目录
cp -r skill/kingdee-k3cloud ~/.workbuddy/skills/ # WorkBuddy
cp -r skill/kingdee-k3cloud ~/.claude/skills/ # Claude Code
# 方式二:打包后导入(适合千问办公 / 图形化导入)
python scripts/package_skill.py # 产出 dist/kingdee-k3cloud-skill.zip
```
导入后对话中提到「金蝶 / ERP / 单据 / 库存 / 日报」等词即会触发。详见 [docs/skill-import.md](docs/skill-import.md)。
---
## 工具清单
**查询(只读模式可用)**
| 工具 | 说明 |
|---|---|
| `ping` | 测试连接与认证 |
| `list_forms` | 列出常用表单(可按关键字过滤) |
| `get_form_fields` | 获取表单字段元数据 |
| `query_bill` | 查询单据(二维数组,分页) |
| `query_bill_json` | 查询单据(JSON,字段名为 key) |
| `count_bill` | 估算满足条件的行数 |
| `view_bill` | 查看单条单据详情 |
| `query_bill_all` | 自动翻页拉全量 |
| `query_bill_range` | 按日期分片查询(可落盘) |
| `export_bill_to_file` | 流式导出 ndjson / csv |
**写入(仅 `MCP_MODE=readwrite` 注册)**
| 工具 | 说明 |
|---|---|
| `save_bill` | 新建 / 保存单据 |
| `submit_bill` | 提交 |
| `audit_bill` | 审核 |
| `unaudit_bill` | 反审核 |
| `delete_bill` | 删除 |
| `execute_operation` | 自定义操作(禁用等) |
| `push_bill` | 下推 |
所有工具统一返回:
```json
{"ok": true, "tool": "<name>", "data": { ... }}
{"ok": false, "error": {"code": "...", "message": "...", "hint": "..."}}
```
---
## 安全模型
四层纵深防御:
1. **工具层**:`MCP_MODE=readonly` 时写入工具不注册;写入工具内部再校验一次。
2. **数据层(唯一可信源)**:金蝶集成用户的功能 / 数据权限决定能读哪些组织、能写哪些单据。
3. **连接层**:可选 `MCP_API_KEY` 强制鉴权;生产建议置于反向代理 + TLS 之后。
4. **审计层**:每次调用写结构化审计,`app_secret` 等字段自动替换为 `***REDACTED***`。
**多用户要点**:审计要归因到人,必须 **一人一个金蝶集成用户(AppID)**;共用 AppID 只能追到"某个集成用户",无法区分真人。
**已知限制**:上游官方 SDK 内部使用 `verify=False`(不校验 TLS 证书),请务必部署在内网 / 可信网段。
---
## 上线前联调
容器能跑 ≠ 业务已通。请在测试账套逐项确认:
- [ ] `ping` 返回 `ok: true`
- [ ] `get_form_fields` 能取到真实字段(核对表单 ID 与字段名)
- [ ] `query_bill` 取回 1 条真实单据
- [ ] `count_bill` 与 ERP 界面行数一致
- [ ] `export_bill_to_file` 落盘成功
- [ ] 只读模式下写入工具**不可见**
- [ ] `readwrite` 下演练 `save → submit → audit → unaudit → delete`
- [ ] 金蝶集成用户权限最小化
- [ ] 审计日志可按 AppID 检索
---
## 项目结构
```
kingdee-k3cloud-mcp/
├── src/kingdee_k3cloud_mcp/ # MCP 服务端
│ ├── config.py # 环境变量校验
│ ├── client.py # 官方 SDK 封装
│ ├── pagination.py # 翻页 / 日期分片
│ ├── audit.py # 审计
│ ├── security.py # API Key 中间件
│ └── tools/ # 工具实现(query / export / write / meta)
├── skill/kingdee-k3cloud/ # 配套 Skill
├── docs/ # 部署 / 客户端 / Skill 文档
├── scripts/ # 技能打包脚本
├── tests/ # 单元测试
├── Dockerfile
└── docker-compose.yml
```
---
## 开发
```bash
python -m venv .venv
. .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
ruff check .
pytest
```
---
## 许可证
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues