Kingdee MCP Server —— 让 AI 直接操作金蝶云星空 ERP
⚠️ 本项目为第三方开源，非金蝶官方出品，与金蝶软件（Kingdee）无任何隶属或授权关系。
Kingdee MCP Server 是金蝶云星空（Kingdee Cloud Star）ERP 的 MCP（Model Context Protocol） 服务端，让 Claude、Cursor、Windsurf、Cline 等 AI 助手能够通过自然语言直接操作金蝶 ERP 系统。
官方网站：https://wahailong.github.io/KingdeeMCP/
为什么需要金蝶 MCP？
传统 ERP 操作繁琐，需要在多个界面间切换。有了 金蝶 MCP Server，你可以：
- 直接对 AI 说："查询本月已审核的采购订单"
- 直接对 AI 说："帮我新建一张销售订单"
- 直接对 AI 说："审核这几张入库单"
- 在微信、WhatsApp、Telegram 中通过 OpenClaw 操作金蝶
AI 会自动调用金蝶 API 完成操作，无需手动登录 ERP 界面。
对实施与开发的价值
实施阶段
- 快速验证配置：用自然语言直接查数据，无需登录 ERP 界面逐层点菜单
- 数据核查：批量查询单据状态、库存数量，快速定位问题
- 客户演示：现场说"查一下你们的采购订单"，AI 实时返回结果，演示效果直观
日常使用
- 业务人员自助查询，减少依赖实施人员的频率
- 批量提交、审核单据，替代重复的手工操作
- 通过微信 / WhatsApp 直接操作金蝶，无需打开 ERP 客户端
开发阶段
- 用
kingdee_list_forms、kingdee_get_fields快速探索表单结构，替代翻文档 - 自然语言调试接口，比手写 API 请求效率更高
- 可作为内部工具基础进行二次开发，快速扩展自定义工具
支持的 AI 客户端
功能特性
- 101 个工具：覆盖生产、成本、资产、审计、采购、销售、库存、单据附件、财务、委外加工、财务报表等 17 大业务域
- 元数据动态查询：
get_bill_template/validate_bill/refresh_metadata，元数据本地缓存 - 4 个 SQL Server 探查工具：搜索表、搜索字段、查看表结构、金蝶元数据候选发现
- 自然语言操作：用中文直接描述需求，AI 自动转换为 API 调用
- 异步高性能：基于 async/await，支持并发请求
- 自动重试：Session 过期自动重登，连接失败自动重试
- 安全认证：采用金蝶官方 WebAPI 认证，账号密码(ValidateUser)登录，兼容公有云和私有云，无第三方应用授权
- 类型安全：基于 Pydantic 数据验证，参数自动补全
- 易于扩展：基于 FastMCP 框架，轻松添加自定义工具
- 使用示例：提供 9 个常见业务场景示例，覆盖查询、新建、审核、下推等操作
快速安装
pip install kingdee-mcp
或使用 uvx 直接运行（推荐，无需手动安装）：
uvx kingdee-mcp
远程部署（HTTP / SSE 模式）
默认以 stdio 模式运行（本地 MCP 客户端通过子进程调用）。若要把服务部署到服务器、或用网关/托管平台（如 Smithery）远程调用、免客户端安装，可改用 HTTP 类传输：
# SSE 模式（兼容性好，旧客户端首选）
uvx kingdee-mcp --transport sse --host 0.0.0.0 --port 8000
# Streamable HTTP 模式（MCP 新版推荐）
uvx kingdee-mcp --transport streamable-http --host 0.0.0.0 --port 8000
- SSE 端点：
http://<host>:<port>/sse - Streamable HTTP 端点：
http://<host>:<port>/mcp
远程模式下仍需金蝶账号密码（通过
KINGDEE_*环境变量注入）。HTTP 只是传输通道，并不替代金蝶认证——客户端连上来后，工具调用照样要走金蝶 ValidateUser 登录。
也可用环境变量代替命令行参数：KINGDEE_MCP_TRANSPORT（stdio/sse/streamable-http）、KINGDEE_MCP_HOST、KINGDEE_MCP_PORT。
Docker 部署
不想在服务器上折腾 Python 环境的，直接用容器。
方式一：拉现成镜像（最快）
docker run --rm -p 8000:8000 --env-file .env ghcr.io/wahailong/kingdeemcp:latest
镜像随每次发版自动构建推送，latest 跟最新 tag 走，也可以锁定具体版本号如 :0.2.2。
方式二：docker compose（推荐长期运行）
cp .env.example .env # 填 4 个 KINGDEE_* 变量
docker compose up -d
docker compose logs -f
方式三：本地自己构建
docker build -t kingdee-mcp .
# 国内网络慢可换 pip 源：
docker build --build-arg PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/ -t kingdee-mcp .
起来之后 MCP 客户端连 http://<宿主机IP>:8000/mcp（Streamable HTTP）。
几个容易踩的点：
- 容器默认以
streamable-http模式监听0.0.0.0:8000。别改回 127.0.0.1 —— 那样只有容器内部能连，宿主机映射了端口也访问不到。 - 想让容器当本地 MCP 客户端的子进程用（stdio 模式）：
docker run -i --rm --env-file .env -e KINGDEE_MCP_TRANSPORT=stdio ghcr.io/wahailong/kingdeemcp:latest - 配置对不对，先自检一把（不起服务，只跑一次金蝶登录）：
docker run --rm --env-file .env ghcr.io/wahailong/kingdeemcp:latest --check - 容器里跑的是金蝶 API 那部分。SQL Server 直连探查工具还需要额外装微软 ODBC 驱动（
msodbcsql18），镜像里只预装了unixodbc基础库。
配置教程
第一步：金蝶云星空后台授权
- 准备一个金蝶云星空账号（建议专用集成账号，不要用 Administrator）
- 本服务采用**账号密码(ValidateUser)**登录，无需创建第三方应用、也无需 AppID / AppSecret
- 为该账号分配所需模块的操作权限
第二步：配置 MCP 客户端
在你的 MCP 客户端配置文件中添加以下内容：
{
"mcpServers": {
"kingdee": {
"command": "uvx",
"args": ["kingdee-mcp"],
"env": {
"KINGDEE_SERVER_URL": "http://your-server/k3cloud/",
"KINGDEE_ACCT_ID": "你的账套ID",
"KINGDEE_USERNAME": "金蝶账号",
"KINGDEE_PASSWORD": "金蝶账号密码"
}
}
}
}
配置文件位置：
第三步：重启客户端
配置完成后重启你的 MCP 客户端即可开始使用。
OpenClaw 用户：使用
openclaw mcp set配置后会自动热加载，无需重启网关。
环境变量说明
⚠️ 从 0.1.0 升级的破坏性变更（重要）
0.2.0 起，登录方式从「第三方应用授权（AppID + AppSecret）」改为「账号密码（ValidateUser）」，旧版的 KINGDEE_APP_ID / KINGDEE_APP_SEC 环境变量已失效。
如果你之前的 MCP 客户端配置里用的是 AppID / AppSecret，升级后会出现登录失败。请按以下方式迁移：
- 在金蝶云星空创建一个专用集成账号（不要用 Administrator）；
- 把 MCP 配置里的环境变量改为：删除
KINGDEE_APP_ID、KINGDEE_APP_SEC，新增KINGDEE_PASSWORD= 该集成账号的密码； - 重启 MCP 客户端。
之所以改用账号密码，是因为账号密码(ValidateUser) 是以真实用户身份执行 WebAPI、会携带该用户自身的业务权限（含 WebApi 数据权限控制）；而第三方应用授权(LoginByAppSecret) 以应用身份登录、不携带真实用户权限，报表等依赖数据权限的查询会受应用授权范围限制，无法按用户权限正常执行。
可用工具列表
共 101 个工具，按业务域分组（每组列出代表性工具，完整清单见 src/kingdee_mcp/server.py）：
元数据探查含 4 个 SQL Server 工具（
kingdee_discover_tables/kingdee_discover_columns/kingdee_describe_table/kingdee_discover_metadata_candidates），需配置MCP_SQLSERVER_*环境变量。
元数据查询
数据查询（只读操作）
单据操作（写操作）
单据附件（WebAPI V6.0）
附件工具不读写 MCP 服务器上的本地文件。上传完成不会自动提交或审核单据。 使用方式、字段映射和失败恢复见 单据附件示例。
使用示例
配置完成后，在 Claude 或其他 AI 客户端中直接用自然语言操作：
# 查询类
查询最近 20 条已审核的采购订单
查一下物料编码 MAT001 的即时库存
查询客户编码 C001 的所有销售订单
显示本月所有未提交的销售订单
# 操作类
帮我新建一张采购订单，供应商 S001，物料 MAT001，数量 100，单价 10.5
审核这几张采购入库单：12345, 12346, 12347
反审核销售订单 SO2024001
SQL Server 探查工具（可选）
配置 MCP_SQLSERVER_* 环境变量后可用，帮助理解金蝶数据库结构：
典型用法：先问 AI "采购订单在数据库里对应哪张表"，再用 kingdee_describe_table 看字段结构。
支持的单据类型（form_id）
常见问题
Q: 提示认证失败怎么办？ 检查金蝶账号与密码(KINGDEE_PASSWORD)是否正确，该账号是否有对应模块的操作权限。
Q: 连接超时怎么解决？
检查 KINGDEE_SERVER_URL 是否正确（需包含 /k3cloud/ 后缀），确保服务器可访问。
Q: 支持金蝶云星空公有云吗？ 支持。公有云和私有云使用相同的账号密码(ValidateUser)认证方式，配置方式完全一致。
Q: 用 uvx kingdee-mcp 启动时报 No module named 'mcp.server.fastmcp'？
这是 uvx 的临时环境偶尔没把依赖（mcp）装全导致的，不是包本身的问题（PyPI 元数据已正确声明 mcp[cli]>=1.0.0）。两种解决方式：
-
清理 uv 缓存后重试：
uv cache clean，再重新启动uvx kingdee-mcp； -
或改用 pip 安装 + 模块方式启动（更稳，推荐用于生产）：
pip install kingdee-mcpMCP 客户端配置改为：
{ "mcpServers": { "kingdee": { "command": "python", "args": ["-m", "kingdee_mcp.server"], "env": { "KINGDEE_SERVER_URL": "...", "KINGDEE_ACCT_ID": "...", "KINGDEE_USERNAME": "...", "KINGDEE_PASSWORD": "..." } } } }
配合 mcp-sqlserver-introspect 使用
kingdee-mcp 提供两层能力：
第一层：ERP 操作层（kingdee-mcp 内置） 直接操作金蝶单据：查询、新建、提交、审核、下推等。
第二层：数据库理解层（mcp-sqlserver-introspect） 探查 SQL Server 表结构：找表、找字段、理解关联关系。
典型使用场景：
# 场景一：接口映射
问："帮我找采购订单相关的表"
→ mcp-sqlserver-introspect 返回 T_PUR_PurchaseOrder 等表
→ 确认 Kingdee API 字段和数据库字段的对应关系
# 场景二：字段溯源
问："帮我查 FTotalAmount 这个字段在哪些表里"
→ mcp-sqlserver-introspect 返回包含该字段的表列表
# 场景三：数据核查
先用 mcp-sqlserver-introspect 探索表结构
再用 kingdee-mcp 操作 ERP 数据
两者配合，AI 既能理解数据库，又能操作 ERP
mcp-sqlserver-introspect 项目地址：https://gitee.com/lzhrick123/mcp-sqlserver-introspect1
kingdee-mcp 已内置 SQL Server 探查工具（配置
MCP_SQLSERVER_*环境变量即可使用），无需额外安装 mcp-sqlserver-introspect。
Q: 如何添加自定义工具？
基于 FastMCP 框架，在 server.py 中添加 @mcp.tool() 装饰器方法即可扩展。
相关链接
贡献者致谢
感谢为本项目贡献代码的开发者：
欢迎提交 Issue 和 Pull Request。新增单据查询工具建议附带 FORM_CATALOG 条目、常用过滤示例与 mock 测试。
联系方式
- QQ：1724349716
- 邮箱：[email protected]
License
MIT © WaHaiLong