Skip to main content
Glama
Kingdee K3Cloud MCP

Kingdee K3Cloud MCP

Kingdee K3Cloud MCP

License: MIT Python MCP

面向 金蝶云星空(K3Cloud) 的企业级 MCP 服务端 + 配套 Agent Skill。

  • 服务端:一个容器,客户填好环境变量即可运行,向 AI 暴露 17 个 ERP 工具。

  • Skill:一份技能包,导入支持 Skill 机制的 Agent(WorkBuddy、Claude Code、千问办公等)即可获得表单字段与业务工作流知识。

两者可独立使用:只用 MCP 也有完整工具;叠加 Skill 后 Agent 更少踩坑。


目录

详细文档:

文档

内容

docs/deploy.md

服务端部署(Docker / 离线内网 / Python / 传输模式 / 升级)

docs/client-setup.md

客户端配置(WorkBuddy / Claude / Cursor / Cline / 千问办公等)

docs/skill-import.md

Skill 导入(各 Agent 目录与打包方式)


Related MCP server: >>Kingdee MCP Server

特性

  • 开箱即用:环境变量配好即跑,无需手改配置文件、无需编译。

  • 只读 / 读写双模式:只读模式下 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. 启动服务

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 为例):

{
  "mcpServers": {
    "kingdee-k3cloud": {
      "url": "http://<host>:8000/sse",
      "type": "sse"
    }
  }
}

接入后调用 ping,返回 {"ok": true, ...} 即成功。各客户端详细位置见 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。


Skill 导入

Skill 是知识包,不是连接器:它告诉 Agent 用哪个表单、哪个字段、怎么查,实际执行仍由 MCP 完成。

Agent

Skill 机制

导入方式

WorkBuddy

✅

复制到 ~/.workbuddy/skills/kingdee-k3cloud/

Claude Code

✅

复制到 ~/.claude/skills/kingdee-k3cloud/

千问办公

✅(按版本)

技能 / 插件导入入口,选择目录或技能包

其他支持 Skills 的 Agent

✅

放入其 skills 目录,或导入打包后的 zip

仅支持 MCP 的客户端

❌

直接用 MCP 的 17 个工具,不影响功能

# 方式一:直接复制目录
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。


工具清单

查询(只读模式可用)

工具

说明

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

下推

所有工具统一返回:

{"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

开发

python -m venv .venv
. .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
ruff check .
pytest

许可证

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants such as Claude, Cursor, and Windsurf to query and operate Kingdee Cloud Star ERP through natural language, exposing 87 tools across purchasing, sales, inventory, production, cost accounting, fixed assets, auditing, and financial reporting. Supports read and write operations including bill creation, submission, auditing, and un-auditing.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants such as Claude, Cursor, and Windsurf to query and operate Kingdee Cloud Star ERP (purchasing, sales, inventory, finance, production, and more) using natural language across 87 tools. It supports bill creation, submission, auditing, un-auditing, pushing, metadata exploration, and financial report retrieval with account-password authentication on both public and private clouds.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables Claude, Cursor, and other AI assistants to query and operate Kingdee Cloud Star ERP in natural language, covering purchasing, sales, inventory, production, cost, assets, and financial reporting. It exposes 87 tools for reading documents, creating and modifying bills, submitting, auditing, unauditing, pushing workflows, and exploring form metadata.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants such as Claude, Cursor, and Windsurf to query and operate Kingdee Cloud Star ERP using natural language. It exposes 87 tools across purchasing, sales, inventory, financial reporting, production, cost, assets, and approval workflows, including creating, submitting, auditing, and querying business documents.
      -