接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
金蝶MCP Server(Kingdee K3Cloud MCP)面向金蝶云星空 ERP,让 AI 助手(Claude Desktop、Claude Code、Cursor、Windsurf、Cline、Continue、Cherry Studio 等任意支持 MCP 协议的客户端)通过自然语言查询和操作金蝶 ERP 系统。标准 PyPI 包,pip install 或 uvx 均可直接运行,无需绑定特定包管理器。
提示:通过 Openclaw 等支持 MCP 的 Agent 平台接入后,可在其支持的 IM 渠道(如微信、Telegram)中用自然语言查库存、查单据,无需打开金蝶网页端。支持 Skill 机制的 AI Agent(Claude Code、Openclaw 等)还可配合 kingdee-k3cloud-skill 获得更佳体验——Skill 为 Agent 注入金蝶表单字段、常用查询模式和工作流知识,大幅减少试错次数,但并非必需,MCP Server 本身即可独立配合任意 MCP 客户端使用全部工具。
┌─────────────────────┐ ┌─────────────────────┐ ┌──────────────────┐
│ kingdee-k3cloud │───▶│ kingdee-k3cloud │───▶│ K3Cloud Web API │
│ -skill │ │ -mcp │ │ (金蝶云星空) │
│ 知识库 / 工作流 │ │ 执行引擎 / MCP工具 │ │ │
└─────────────────────┘ └─────────────────────┘ └──────────────────┘
支持 Skill 的 Agent 所有 MCP 客户端通用
MCP Server for Kingdee K3Cloud ERP. Connect AI assistants to your ERP system via the Model Context Protocol.
form_id 参数支持物料、客户、销售订单、采购订单等所有表单,无需为每种业务单独配置query_bill_all(自动翻页)、query_bill_to_file(流式落盘)、query_bill_range(日期分片),彻底消除模型手动循环的负担pip install 即可安装,仅需 Python 3.10+,无强制包管理器依赖pip install kingdee-k3cloud-mcp
kingdee-k3cloud-mcp
标准 PyPI 包,仅需 Python 3.10+,不依赖 uv。注意:服务启动时必须提供 5 个必填环境变量(KD_SERVER_URL、KD_ACCT_ID、KD_USERNAME、KD_APP_ID、KD_APP_SEC),否则会报错退出。
在 MCP 客户端中使用(推荐,见下方"客户端配置"章节):通过客户端配置的 env 字段传入。
手动测试时,可通过以下任一方式提供环境变量:
# 方式 A:在当前目录创建 .env 文件(服务启动时自动加载)
cp .env.example .env # 填写真实值后再运行
kingdee-k3cloud-mcp
# 方式 B:在命令行临时导出
export KD_SERVER_URL=https://your-server/k3cloud/
export KD_ACCT_ID=your_acct_id
export KD_USERNAME=your_username
export KD_APP_ID=your_app_id
export KD_APP_SEC=your_app_secret
kingdee-k3cloud-mcp
无需 pip install,uvx 会自动创建隔离环境并运行,用法与上面完全一致,把 kingdee-k3cloud-mcp 换成 uvx kingdee-k3cloud-mcp 即可:
cp .env.example .env
uvx kingdee-k3cloud-mcp
git clone https://github.com/adamzhang1987/kingdee-k3cloud-mcp.git
cd kingdee-k3cloud-mcp
uv sync
uv run kingdee-k3cloud-mcp
复制环境变量模板并填写:
cp .env.example .env
第三方应用 ID 和密钥需在金蝶云星空管理端的「第三方系统登录授权」中申请。
在金蝶云星空产品中配置第三方系统集成,需按以下步骤获取 5 个环境变量:
注意:当前数据库中心 ID(即账套 ID)可以通过生成测试链接弹出的信息中获取。
金蝶服务器地址,格式为 https://your-server/k3cloud/,其中:
your-server 为金蝶云星空服务器的域名或 IP 地址/k3cloud/ 结尾https://erp.company.com/k3cloud/使用具有相关模块操作权限的账号,不建议使用管理员账号。建议新建一个专门的集成用户账号,并为其分配所需的模块操作权限。
注意:如需查看 APP_SECRET,可随时在应用详情中查看;如遗失,也可通过「重置」功能重新生成。
配置完成后,可通过以下命令验证连接:
cd kingdee-k3cloud-mcp
cp .env.example .env
# 编辑 .env 填写上述 5 个环境变量
uvx kingdee-k3cloud-mcp
如看到「MCP Server running」或类似输出,表示配置成功。
参考文档:金蝶云星空第三方系统集成配置指南
以下所有客户端配置都用 "command": "uvx" 免安装启动;若已 pip install kingdee-k3cloud-mcp,把 "command": "uvx" 改成 "command": "kingdee-k3cloud-mcp" 并删掉 "args" 中的包名(保留其余参数如 --mode readonly)即可,两种方式效果完全一致。
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS):
{
"mcpServers": {
"kingdee-k3cloud": {
"command": "uvx",
"args": ["kingdee-k3cloud-mcp"],
"env": {
"KD_SERVER_URL": "https://your-server/k3cloud/",
"KD_ACCT_ID": "your_acct_id",
"KD_USERNAME": "your_username",
"KD_APP_ID": "your_app_id",
"KD_APP_SEC": "your_app_secret",
"KD_LCID": "2052"
}
}
}
}
在项目目录下创建 .mcp.json:
{
"mcpServers": {
"kingdee-k3cloud": {
"command": "uvx",
"args": ["kingdee-k3cloud-mcp"],
"env": {
"KD_SERVER_URL": "https://your-server/k3cloud/",
"KD_ACCT_ID": "your_acct_id",
"KD_USERNAME": "your_username",
"KD_APP_ID": "your_app_id",
"KD_APP_SEC": "your_app_secret",
"KD_LCID": "2052"
}
}
}
}
Cursor:Settings → MCP → Add new MCP Server;Windsurf:编辑 ~/.codeium/windsurf/mcp_config.json。两者配置格式与 Claude Desktop 一致:
{
"mcpServers": {
"kingdee-k3cloud": {
"command": "uvx",
"args": ["kingdee-k3cloud-mcp"],
"env": {
"KD_SERVER_URL": "https://your-server/k3cloud/",
"KD_ACCT_ID": "your_acct_id",
"KD_USERNAME": "your_username",
"KD_APP_ID": "your_app_id",
"KD_APP_SEC": "your_app_secret",
"KD_LCID": "2052"
}
}
}
}
配置结构与上面完全一致——command + args + env,填入相同的 uvx kingdee-k3cloud-mcp 与 5 个环境变量即可。具体填写位置参考各客户端自己的 MCP 配置文档:
~/.continue/config.json 的 mcpServers 字段Openclaw 是支持 Skill 机制的 Agent 平台,可将本 MCP Server 接入其支持的 IM 渠道(如微信、Telegram),实现"发一句话查金蝶库存/单据"。配置方式同样是标准 MCP Server 声明(command/args/env),具体接入步骤参考 Openclaw 官方文档;配合 kingdee-k3cloud-skill 使用可进一步减少字段试错。IM 渠道的具体支持范围由 Openclaw 平台决定。
如需多人共用同一个服务实例:
# 启动 SSE 服务(默认端口 8000)
FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=8080 uvx kingdee-k3cloud-mcp --transport sse
客户端连接地址:http://your-server:8080/sse
可通过 MCP_API_KEY 环境变量启用 Bearer Token 鉴权。
所有工具通过 form_id 参数支持任意表单(物料、客户、供应商、销售订单、采购订单等)。
通过 --mode readonly 或 MCP_MODE=readonly 限制服务器只暴露 8 个查询工具,防止 AI 误操作写入数据。
"args": ["kingdee-k3cloud-mcp", "--mode", "readonly"]
或:
"env": {
"MCP_MODE": "readonly",
...
}
MCP Server 本身不实现数据权限模型——它以「第三方系统登录授权」方式接入金蝶云星空,身份固定为 .env 中的 KD_ACCT_ID(账套)+ KD_USERNAME(集成用户)+ KD_ORG_NUM(组织,默认 0)。所有工具调用共享这一个身份,不支持按调用方切换用户,因此 AI 能看到什么数据,完全由这个集成用户在星空里的权限配置决定。
SAL_SaleOrder)+ 允许的操作(查询/新增/提交/审核)KD_ORG_NUM这两者是权限的补充,不能替代星空侧的权限配置:
--mode readonly / MCP_MODE=readonly:全局禁用所有写入工具MCP_API_KEY:SSE / streamable-http 传输下的连接鉴权(stdio 模式不涉及)⚠️ 第二种情况容易被误判为"该时间段确实没有数据"——count_bill / query_bill* 拿到的是权限过滤后的结果,本身无法区分"真没数据"和"被权限挡了"。
使用 MCP Inspector 可视化调试工具:
uvx mcp dev src/kingdee_k3cloud_mcp/server.py
AI 助手(Claude Desktop / Claude Code / Cursor / Cline / Openclaw 等)
│ MCP 协议
▼
kingdee-k3cloud-mcp(本项目)
│ Kingdee Web API SDK
▼
金蝶云星空 K3Cloud
本项目使用官方金蝶 Python SDK(kingdee-cdp-webapi-sdk)与 K3Cloud API 通信,并通过 FastMCP 将其封装为标准 MCP 工具。
金蝶 ERP 的 MCP 集成方案不止一种,各有侧重。本项目更适合以下场景:
--mode readonly 提供只读边界;启动时自动校验凭据,配置错误在启动日志里就能看到,不必等到第一次工具调用;认证失败会返回明确的诊断而非误导文案,排障不靠猜query_bill_all(自动翻页)、query_bill_to_file(流式落盘)、query_bill_range(日期分片)三个高阶原语专门处理万行级数据,避免让模型手写翻页循环query_metadata 工具可让 AI 在查询前自行发现表单的实际字段结构,不依赖预置字段表;配合 kingdee-k3cloud-skill 还可把企业专属的表单/字段/审批流封装成可复用的知识如果你的场景是个人轻量试用、追求几分钟内跑通第一次查询,本项目同样支持 pip install 一步安装、开箱即用;具体选哪个方案,取决于你更看重「装上就能用」还是「长期在生产环境里稳定跑」。
让 AI 直接通过 Skill 构造 HTTP 请求访问 ERP,技术上可行,但会引入一系列安全隐患。MCP 的进程隔离模型从根本上解决了这些问题。
MCP Server 以独立进程运行,凭证(KD_APP_SEC、服务器地址、账套 ID)通过环境变量注入,模型永远看不到这些信息。如果改用 Skill 直接调用,凭证必须出现在提示词或对话上下文中,一旦对话日志被导出、上下文被截图,或模型意外将其输出,机密就泄露了。
Skill 是"建议"——模型可能理解有误,也可能被精心构造的输入绕过。MCP Server 的 --mode readonly 则是物理限制:写入工具根本不存在于工具列表中,模型想用也用不了。这是"告诉实习生不要删数据"和"实习生根本没有 DELETE 权限"之间的本质区别。
MCP Server 部署在企业内网(或本机),可直接访问内部 ERP;LLM 运行在云端,从不直接接触内部网络。使用 stdio 传输时,所有 ERP 流量都在本机进程间流转,不经过任何外部网络。
每一次工具调用都经过 MCP Server,可在此统一记录操作类型、参数、时间戳和调用来源。直接调用方式下,AI 的每次请求对企业安全团队来说是不可见的黑盒。
集成用户(KD_USERNAME)可在金蝶系统内被限制为特定模块、只读权限。MCP Server 继承并传递这些限制,LLM 无需感知权限边界,权限边界自然生效。
将 LLM 视为不可信的外部调用方(而非可信的内部系统)是正确的零信任设计思路。MCP 层的存在,使 Skill 和 MCP 的职责分离清晰:Skill 负责"什么时候用、怎么用"(策略),MCP 负责"能做什么"(机制)。即使未来模型能力更强,或出现提示词注入攻击,最坏情况下的爆炸半径也被 MCP Server 的权限模型所限定,而不是依赖模型的"自觉"。
kingdee-k3cloud-skill 是面向支持 Skill 机制的 AI Agent(Claude Code、openclaw、hermes 等)的配套 Skill,提供:
安装后 Agent 可自动掌握金蝶 ERP 的正确查询方式,无需反复试错。
git clone https://github.com/adamzhang1987/kingdee-k3cloud-mcp.git
cd kingdee-k3cloud-mcp
uv sync --dev
make test # 运行测试(覆盖率报告)
make lint # ruff check + mypy
make format # ruff format + fix
make build # uv build + twine check
安装 pre-commit hooks(可选,与 CI 保持一致):
uv run pre-commit install
Made with contrib.rocks.
Apache License 2.0 — 详见 LICENSE
金蝶MCP Server(Kingdee K3Cloud MCP):让 Claude、Cursor 等 AI 助手通过自然语言查询和操作金蝶云星空 ERP。
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Kingdee K3cloud 透過 stdio 在本機執行。
上次檢查時間:2026-11-10。 金蝶MCP Server(Kingdee K3Cloud MCP):让 Claude、Cursor 等 AI 助手通过自然语言查询和操作金蝶云星空 ERP。