Kingdee MCP Server —— 让 AI 直接操作金蝶云星空 ERP
⚠️ 本项目为第三方开源,非金蝶官方出品,与金蝶软件(Kingdee)无任何隶属或授权关系。
Potencialize seu agente
O comando do próprio publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
uvx kingdee-mcp==0.2.4O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
KINGDEE_SERVER_URL=<value> KINGDEE_ACCT_ID=<value> KINGDEE_USERNAME=<value> KINGDEE_PASSWORD=<secret> claude mcp add wahailong-kingdeemcp -- uvx kingdee-mcp==0.2.4Execute em um terminal.
{ "mcpServers": { "wahailong-kingdeemcp": { "command": "uvx", "args": [ "kingdee-mcp==0.2.4" ], "env": { "KINGDEE_SERVER_URL": "<value>", "KINGDEE_ACCT_ID": "<value>", "KINGDEE_USERNAME": "<value>", "KINGDEE_PASSWORD": "<secret>" } } }}claude_desktop_config.json
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirKingdee MCP Server 是金蝶云星空(Kingdee Cloud Star)ERP 的 MCP(Model Context Protocol) 服务端,让 Claude、Cursor、Windsurf、Cline 等 AI 助手能够通过自然语言直接操作金蝶 ERP 系统。
传统 ERP 操作繁琐,需要在多个界面间切换。有了 金蝶 MCP Server,你可以:
AI 会自动调用金蝶 API 完成操作,无需手动登录 ERP 界面。
实施阶段
日常使用
开发阶段
kingdee_list_forms、kingdee_get_fields 快速探索表单结构,替代翻文档get_bill_template / validate_bill / refresh_metadata,元数据本地缓存pip install kingdee-mcp
或使用 uvx 直接运行(推荐,无需手动安装):
uvx kingdee-mcp
默认以 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
http://<host>:<port>/ssehttp://<host>:<port>/mcp远程模式下仍需金蝶账号密码(通过
KINGDEE_*环境变量注入)。HTTP 只是传输通道,并不替代金蝶认证——客户端连上来后,工具调用照样要走金蝶 ValidateUser 登录。
也可用环境变量代替命令行参数:KINGDEE_MCP_TRANSPORT(stdio/sse/streamable-http)、KINGDEE_MCP_HOST、KINGDEE_MCP_PORT。
不想在服务器上折腾 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 —— 那样只有容器内部能连,宿主机映射了端口也访问不到。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
msodbcsql18),镜像里只预装了 unixodbc 基础库。在你的 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.2.0 起,登录方式从「第三方应用授权(AppID + AppSecret)」改为「账号密码(ValidateUser)」,旧版的 KINGDEE_APP_ID / KINGDEE_APP_SEC 环境变量已失效。
如果你之前的 MCP 客户端配置里用的是 AppID / AppSecret,升级后会出现登录失败。请按以下方式迁移:
KINGDEE_APP_ID、KINGDEE_APP_SEC,新增 KINGDEE_PASSWORD = 该集成账号的密码;之所以改用账号密码,是因为账号密码(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_*环境变量。
附件工具不读写 MCP 服务器上的本地文件。上传完成不会自动提交或审核单据。 使用方式、字段映射和失败恢复见 单据附件示例。
配置完成后,在 Claude 或其他 AI 客户端中直接用自然语言操作:
# 查询类
查询最近 20 条已审核的采购订单
查一下物料编码 MAT001 的即时库存
查询客户编码 C001 的所有销售订单
显示本月所有未提交的销售订单
# 操作类
帮我新建一张采购订单,供应商 S001,物料 MAT001,数量 100,单价 10.5
审核这几张采购入库单:12345, 12346, 12347
反审核销售订单 SO2024001
配置 MCP_SQLSERVER_* 环境变量后可用,帮助理解金蝶数据库结构:
典型用法:先问 AI "采购订单在数据库里对应哪张表",再用 kingdee_describe_table 看字段结构。
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-mcp
MCP 客户端配置改为:
{
"mcpServers": {
"kingdee": {
"command": "python",
"args": ["-m", "kingdee_mcp.server"],
"env": { "KINGDEE_SERVER_URL": "...", "KINGDEE_ACCT_ID": "...", "KINGDEE_USERNAME": "...", "KINGDEE_PASSWORD": "..." }
}
}
}
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 测试。
MIT © WaHaiLong
金蝶云星空 MCP Server:让 Claude/Cursor 等 AI 助手用自然语言直接查询、操作 ERP(采购/销售/库存/财务/附件等 101 个工具)
{ "mcpServers": { "wahailong-kingdeemcp": { "command": "uvx", "args": [ "kingdee-mcp==0.2.4" ], "env": { "KINGDEE_SERVER_URL": "<value>", "KINGDEE_ACCT_ID": "<value>", "KINGDEE_USERNAME": "<value>", "KINGDEE_PASSWORD": "<secret>" } } }}Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
O publicador lista estas variáveis de ambiente: KINGDEE_SERVER_URL, KINGDEE_ACCT_ID, KINGDEE_USERNAME, KINGDEE_PASSWORD.
KingdeeMCP roda localmente via stdio.
Última verificação: 2026-10-27. 金蝶云星空 MCP Server:让 Claude/Cursor 等 AI 助手用自然语言直接查询、操作 ERP(采购/销售/库存/财务/附件等 101 个工具)