Kingdee K3Cloud ERP
About
MCP Server for Kingdee K3Cloud (金蝶云星空) — one of the most widely used ERP systems in China. Connects AI assistants (Claude Desktop, Cursor, Cline, Cherry Studio, etc.) to Kingdee ERP via natural language.
Details
- Author
- adamzhang1987
- Categories
- Productivity, Other, Database, API, Automation
Jump to
Setup
Install Kingdee K3Cloud ERP in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/adamzhang1987/kingdee-k3cloud-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
金蝶云星空 K3Cloud MCP Server，让 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 theModel Context Protocol.
- 15 个 MCP 工具：覆盖查询、大数据量导出、新增、提交、审核、反审核、删除、下推等核心操作
- 通用接口设计：单一form_id参数支持物料、客户、销售订单、采购订单等所有表单，无需为每种业务单独配置
- 高阶查询原语：query_bill_all（自动翻页）、query_bill_to_file（流式落盘）、query_bill_range（日期分片），彻底消除模型手动循环的负担
- 只读/读写模式：可限制 AI 只能查询，防止误操作
- 自动会话恢复：长时间运行时自动处理会话超时，无需人工干预
- 多传输协议：支持 stdio（本地）、SSE、streamable-http（远程共享）
- 标准 Python 包：pip install即可安装，仅需 Python 3.10+，无强制包管理器依赖
- 类型安全的入参校验：所有工具入参基于类型注解，由 FastMCP 在调用时自动做 Pydantic 运行时校验，参数结构错误会在到达金蝶 API 之前被拦截
- 安装：pip install kingdee-k3cloud-mcp（或用uvx kingdee-k3cloud-mcp免安装直接跑）
- 在金蝶云星空「第三方系统登录授权」中申请应用 ID/密钥，拿到 5 个必填环境变量（见下方配置）
- 把变量填进你的 MCP 客户端配置（见下方客户端配置），保存重启
- 直接用自然语言提问，例如：
- 「查一下上周已审核的销售订单，按金额排序」
- 「XX 物料现在各仓库库存分别是多少」
- 「把 3 月份所有销售出库单导出成 csv」
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
- 使用管理员账号登录金蝶云星空系统，进入「系统管理」菜单下的「第三方系统登录授权」。
- 点击新增按钮，进入新增第三方系统登录授权功能页面。
- 点击”获取应用 ID”按钮，根据提示跳转到Open 网站的第三方系统登录授权页面，点击“新增授权”。
- Open 网站用户根据自身信息进行表单填写。
- 提交成功后会生成应用信息，复制应用信息填入金蝶云星空产品 - 第三方系统登录授权 - 获取应用 ID - 应用信息框中，点击“确认”按钮。
- 配置集成用户。
- 点击“保存”按钮，保存成功后点击“生成测试链接”，测试链接是否成功。
注意：当前数据库中心 ID（即账套 ID）可以通过生成测试链接弹出的信息中获取。
金蝶服务器地址，格式为https://your-server/k3cloud/，其中：
- your-server为金蝶云星空服务器的域名或 IP 地址
- 一般以/k3cloud/结尾
- 示例：https://erp.company.com/k3cloud/
使用具有相关模块操作权限的账号，不建议使用管理员账号。建议新建一个专门的集成用户账号，并为其分配所需的模块操作权限。
5. 获取 KD_APP_ID - 应用 ID 和 KD_APP_SEC - 应用密钥
注意：如需查看 APP_SECRET，可随时在应用详情中查看；如遗失，也可通过「重置」功能重新生成。
cd kingdee-k3cloud-mcp cp .env.example .env # 编辑 .env 填写上述 5 个环境变量 uvx kingdee-k3cloud-mcp
以下所有客户端配置都用"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" } } } }
{ "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" } } } }
Cline / Continue / Cherry Studio 及其他 MCP 客户端
配置结构与上面完全一致——command+args+env，填入相同的uvx kingdee-k3cloud-mcp与 5 个环境变量即可。具体填写位置参考各客户端自己的 MCP 配置文档：
- Cline（VS Code 插件）：MCP Servers 面板 → Configure MCP Servers
- Continue：~/.continue/config.json的mcpServers字段
- Cherry Studio：设置 → MCP 服务器 → 添加服务器
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
所有工具通过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*拿到的是权限过滤后的结果，本身无法区分"真没数据"和"被权限挡了"。
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 工具。
- 需要长期稳定运行的生产环境 AI Agent：--mode readonly提供只读边界，RetryableK3CloudApiSdk内置会话自动恢复（应对长时间运行的超时/断连），无需人工值守重启
- 数据量较大的查询/导出需求：query_bill_all（自动翻页）、query_bill_to_file（流式落盘）、query_bill_range（日期分片）三个高阶原语专门处理万行级数据，避免让模型手写翻页循环
- 有自定义字段 / 二次开发的金蝶部署：query_metadata工具可让 AI 在查询前自行发现表单的实际字段结构，不依赖预置字段表；配合kingdee-k3cloud-skill还可把企业专属的表单/字段/审批流封装成可复用的知识
- 需要多种接入方式共存：同一个 Server 支持 stdio（本地 IDE）、SSE、streamable-http（远程共享部署），也可作为 Openclaw 工具接入 IM 渠道
如果你的场景是个人轻量试用、追求几分钟内跑通第一次查询，本项目同样支持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，提供：
- 常用表单 ID 速查表（BD_MATERIAL、SAL_SaleOrder 等）
- 已验证字段名列表（避免字段名错误导致 500）
- 日报、客户查询、销售分析、库存分析、订单追踪等完整工作流
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
Unified MCP gateway that loads 150+ AI tools into Claude Desktop via a single Docker command on Windows. Routes tool calls across specialized servers (Business Intelligence, API Hub, Content Automation, Intelligence) with centralized logging and governance. Built for teams without dedicated platform engineers.
Integrate Odoo with Large Language Models (LLMs) for enhanced business process automation.
Integrate with Odoo ERP systems to manage business data and operations. Requires external configuration for connection parameters.
A hosted or self-hosted cloud version of Odoo MCP
An MCP server that provides direct access to Odoo ERP system capabilities.
An MCP server for integrating with the Odoo ERP system.
An MCP server for interacting with the Pleasanter low-code/no-code business application platform.
Interact with the Procesio automation platform API.
ServiceNow MCP server: 65 tools over the full REST surface (Table, Aggregate, Attachment, Import Set, Batch, CMDB/IRE, Catalog, Change, Knowledge, Email) with script intelligence, flow tracing, ATF runs, multi-instance profiles and Mermaid diagrams.
Integrate the SpotDraft API into agentic workflows. Requires SpotDraft API credentials.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
