kingdee-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@kingdee-mcp 查看采购订单 20260806JX-01"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Kingdee MCP
金蝶云星空(K3Cloud)MCP Server。通过 Model Context Protocol 让 AI 助手(Cursor、Claude Desktop、Claude Code、Cline、Cherry Studio 等)用自然语言查询和操作金蝶 ERP。已验证部署通过
AI 助手(Cursor / Claude / …)
│ MCP(stdio / SSE)
▼
kingdee-mcp
│ Kingdee Web API SDK
▼
金蝶云星空 K3Cloud功能特性
15 个 MCP 工具:查询、翻页/落盘/日期分片、查看详情、元数据;以及保存、提交、审核、反审核、删除、下推等
通用
form_id:同一套工具适配物料、客户、销售/采购订单、出入库等表单只读 / 读写模式:
readonly时写入工具会从工具列表中移除(并保留运行时守卫)自动会话恢复:会话超时后自动重新登录
多传输协议:
stdio(本地 IDE)、sse/streamable-http(远程)Docker 友好:默认监听
0.0.0.0:8181,可对接阿里云 CLB 等负载均衡
Related MCP server: Kingdee MCP Server
环境要求
Python 3.10+
可访问的金蝶云星空环境
集成用户账号(建议专用账号,按最小权限授权)
快速开始
1. 安装
git clone https://github.com/YanSir1999/kingdee-mcp.git
cd kingdee-mcp
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
pip install -e .2. 配置环境变量
cp .env.example .env编辑 .env:
变量 | 必填 | 说明 |
| 是 | 金蝶地址,建议以 |
| 是 | 账套 ID |
| 是 | 集成用户账号 |
| 建议 | 密码( |
| 否 | SSE 监听地址;Docker/CLB 用 |
| 否 | SSE 端口,默认 |
| 否 |
|
| 否 | SSE/HTTP Bearer Token;不设则不鉴权 |
| 否 | 鉴权元数据对外 URL(启用 |
| 否 | SSE Host 白名单,逗号分隔;解决远程 |
3. 本地启动(stdio)
kingdee-mcp
# 或
kingdee-mcp --transport stdio --mode readonly客户端配置
Cursor(本地 stdio)
项目内 .cursor/mcp.json 示例:
{
"mcpServers": {
"kingdee-mcp": {
"command": "D:\\workspace\\kingdee-mcp\\.venv\\Scripts\\kingdee-mcp.exe",
"cwd": "D:\\workspace\\kingdee-mcp"
}
}
}凭证从项目根目录 .env 加载,无需写进 JSON。
Cursor(远程 SSE)
{
"mcpServers": {
"kingdee-mcp-remote": {
"url": "https://your-domain.example.com/sse"
}
}
}若启用了 MCP_API_KEY:
{
"mcpServers": {
"kingdee-mcp-remote": {
"url": "https://your-domain.example.com/sse",
"headers": {
"Authorization": "Bearer your-secret-api-key"
}
}
}
}Claude Desktop / 其他 MCP 客户端
{
"mcpServers": {
"kingdee-mcp": {
"command": "kingdee-mcp",
"args": ["--mode", "readonly"],
"env": {
"KD_SERVER_URL": "https://your-server/k3cloud/",
"KD_ACCT_ID": "your_acct_id",
"KD_USERNAME": "your_username",
"KD_PASSWORD": "your_password"
}
}
}
}Docker 部署
构建镜像
docker build -t kingdee-mcp:local .镜像默认:
传输:
sse模式:
readonly端口:
8181监听:
0.0.0.0
Compose
仓库已提供通用 docker-compose.yml(本地 build,无内网镜像地址):
docker compose up -d --build阿里云 CLB
典型拓扑:
客户端 https://your-domain/sse
→ CLB(443)
→ 后端 ECS/容器 :8181
→ kingdee-mcp(SSE)建议在 .env 中设置:
FASTMCP_HOST=0.0.0.0
FASTMCP_PORT=8181
MCP_ALLOWED_HOSTS=your-domain.example.com,localhost:*,127.0.0.1:*
MCP_ISSUER_URL=https://your-domain.example.com
MCP_MODE=readonly连通性自检:
curl -i -N -H "Accept: text/event-stream" https://your-domain.example.com/sse正常应返回 200 与 event: endpoint。
可用工具
查询工具(readonly / readwrite)
工具 | 说明 |
| 查询单据(二维数组) |
| 查询单据(JSON,字段名为 key) |
| 估算行数 |
| 自动翻页拉取 |
| 翻页流式落盘(ndjson/csv) |
| 按日期分片 + 翻页 |
| 单条详情 |
| 表单元数据 |
写入工具(仅 readwrite)
工具 | 说明 |
| 保存/新增 |
| 提交 |
| 审核 |
| 反审核 |
| 删除 |
| 自定义操作(禁用/反禁用等) |
| 下推 |
常用 form_id 示例:
FormId | 说明 |
| 物料 |
| 客户 |
| 供应商 |
| 销售订单 |
| 采购订单 |
| 生产订单 |
| 入/出库单 |
只读模式
默认 MCP_MODE=readonly(或 --mode readonly):
写入工具从 MCP 工具列表中移除
即使被直接调用,也会返回
只读模式:写入操作已禁用
kingdee-mcp --mode readonly # 仅查询
kingdee-mcp --mode readwrite # 开放写入自然语言示例
「查一下昨天的销售订单」
「查看采购订单 20260806JX-01」
「付款条件编码 023 是什么」
「统计本月销售订单数量」
调试
# MCP Inspector(远程 SSE)
npx @modelcontextprotocol/inspector https://your-domain.example.com/sse
# 单元测试
pip install -e ".[dev]"
pytest项目结构
kingdee-mcp/
├── src/kingdee_mcp/
│ ├── server.py # MCP Server 与工具实现
│ └── form_id_reference.py # 常用 FormId 参考
├── tests/
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── LICENSE
├── NOTICE
├── SECURITY.md
├── pyproject.toml
├── README.md
└── README.en.md安全建议
不要将
.env提交到 Git(详见 SECURITY.md)生产环境优先
MCP_MODE=readonly远程 SSE 建议设置
MCP_API_KEY,并配置MCP_ALLOWED_HOSTS金蝶侧使用专用集成用户,按模块与数据范围最小化授权
致谢
核心能力与工具设计参考并受益于上游开源项目:
详见 NOTICE。
许可证
Available Tools
8 toolscount_billA
估算某查询条件下的数据行数(不返回数据内容)。用于大数据量查询前的探测。
返回 JSON 格式: {"estimated_rows": N, "is_exact": true/false, "hint": "..."} 当 is_exact=false 时,实际行数 ≥ estimated_rows,建议按月/周分片查询。
Args: form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等 filter_string: 过滤条件。如 "FDate >= '2025-01-01' AND FDate < '2026-01-01'"
Inputs: form_id (required), filter_string. Returns: result
query_billD
Inputs: form_id (required), field_keys (required), limit, start_row, +3 more. Returns: result
query_bill_allA
自动翻页查询直到拉完或达到 max_rows 安全上限。
适合估算 ≤ 数千行的场景。大数据量(> 5000 行)请用 query_bill_to_file(落盘) 或 query_bill_range(日期分片),避免超过 MCP 1 MB 返回限制。
返回格式: {"rows": [...], "row_count": N, "exhausted": true/false, "next_start_row": N, # 仅 exhausted=false 时 "hint": "..."} # 仅 exhausted=false 时
Args: form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等 field_keys: 查询字段,逗号分隔。如 "FBillNo,FDate,FAmount" filter_string: 过滤条件。如 "FDate >= '2025-01-01'" order_string: 排序字段。如 "FDate ASC" max_rows: 安全上限,默认 20000;超过则提前终止并返回 exhausted=false page_size: 每页行数,默认 2000,建议不超过 2000
Inputs: form_id (required), field_keys (required), max_rows, page_size, +2 more. Returns: result
query_bill_jsonD
Inputs: form_id (required), field_keys (required), limit, start_row, +3 more. Returns: result
query_bill_rangeA
按日期自动切片 + 翻页,适合跨月/跨年查询。
将 [date_from, date_to) 按 chunk 切成 N 段,每段独立翻页拉取。 output_path 为空时内联返回(受 MCP 1 MB 限制,适合小跨度); 非空时流式落盘,适合大跨度(年级)查询。
返回格式(内联): {"rows": [...], "row_count": N, "chunks": K, "exhausted": true} 返回格式(落盘): {"path": "...", "row_count": N, "bytes": M, "chunks": K, "format": "ndjson"} 若中途出错:{"error": "...", "path": "...", "row_count": <已写入>, "bytes": M}
Args: form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder 等 field_keys: 查询字段,逗号分隔 date_field: 日期字段名。通常是 FDate 或 FCreateDate date_from: 起始日期(含),YYYY-MM-DD date_to: 结束日期(不含),YYYY-MM-DD extra_filter: 额外过滤条件(与日期条件 AND 拼接) chunk: 切片粒度,month(默认)/ week / day output_path: 落盘路径(绝对路径)。空=内联返回 page_size: 每页行数,默认 2000
Inputs: date_to (required), form_id (required), date_from (required), date_field (required), +5 more. Returns: result
query_bill_to_fileA
自动翻页并流式写入本地文件,适合大数据量导出(万行以上)。
不在内存中累积数据,写入完成后返回文件路径和统计信息。 文件可用 Read 工具抽检,或交由 pandas/polars 处理。
返回格式: {"path": "...", "row_count": N, "bytes": M, "format": "ndjson"} 若中途出错:{"error": "...", "path": "...", "row_count": <已写入>, "bytes": M}
Args: form_id: 表单ID。如 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等 field_keys: 查询字段,逗号分隔。如 "FBillNo,FDate,FAmount" filter_string: 过滤条件。如 "FDate >= '2025-01-01'" output_path: 输出文件绝对路径。如 "/tmp/orders.ndjson" format: 输出格式,ndjson(每行一个 JSON 对象)或 csv,默认 ndjson page_size: 每页行数,默认 2000 max_rows: 最大写入行数,默认 500000;超过则截断并正常返回
Inputs: form_id (required), field_keys (required), format, max_rows, +3 more. Returns: result
query_metadataA
查询金蝶云星空表单的元数据(字段结构信息)。
用于获取某个表单有哪些字段、字段类型等信息,便于构造查询和保存参数。
Args: form_id: 表单ID。如 SUB_ReqChange(委外订单变更单)、SUB_SubReqOrder(委外订单)、 SAL_SaleOrder、PUR_PurchaseOrder、BD_MATERIAL 等
Inputs: form_id (required). Returns: result
view_billA
查看金蝶云星空单条记录的完整详情。
通过编号或内码查看单条记录的所有字段信息。
Args: form_id: 表单ID。如 BD_MATERIAL、SAL_SaleOrder 等 number: 单据编号。如 "MATERIAL001"(number 和 bill_id 二选一) bill_id: 单据内码ID(number 和 bill_id 二选一)
Inputs: form_id (required), number, bill_id. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
The query_bill family contains five tools (query_bill, query_bill_json, query_bill_all, query_bill_to_file, query_bill_range) with heavily overlapping purposes; query_bill and query_bill_json are completely undifferentiated and have no descriptions. While some tools have mode-specific suffixes, an agent could easily select the wrong one without deep inspection.
Tool names follow a consistent lowercase verb_noun pattern (query_, count_, view_), and the query_bill_* variants share a clear prefix. However, the naming doesn't fully clarify the differences between _all, _range, _to_file, and _json, and query_bill vs query_bill_json is ambiguous.
Eight tools is well-scoped for a specialized ERP data access server. Each tool serves a distinct operational mode (basic query, paginated query, date-range query, file export, count, detail, metadata), and the count feels neither thin nor bloated.
The read-query surface is comprehensive: multiple query modes, row counting, single-record detail, and metadata retrieval cover the expected needs for a Kingdee data query MCP. Minor gaps include a lack of form discovery (listing available form IDs) and no write/update operations, but these may be intentionally outside scope.
Maintenance
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
AI for Tally Prime and Tally ERP 9. Hosted MCP server to ask your accounts in any language.
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
Related MCP Servers
- AlicenseAqualityAmaintenanceMCP server for Kingdee K3Cloud ERP that enables AI assistants to query and operate ERP data via natural language through the Model Context Protocol.15409 PyPI104Apache 2.0
- FlicenseNot gradedqualityAmaintenanceEnables Claude, Cursor, Windsurf, and other MCP-compatible AI assistants to query and operate Kingdee Cloud Star ERP in natural language, covering purchasing, sales, inventory, production, costs, fixed assets, approvals, and financial reports. It exposes tools for bill creation, submission, auditing, un-auditing, push-down, metadata/form-field discovery, and optional SQL Server schema exploration.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude, Cursor, and other AI assistants to query and operate Kingdee Cloud Star ERP—covering purchasing, sales, inventory, manufacturing, costing, fixed assets, financial reports, and approvals—using natural language through 87 MCP tools.-
- FlicenseNot gradedqualityAmaintenanceEnables Claude, Cursor, and other AI assistants to query and operate Kingdee Cloud Star ERP in natural language through MCP tools. It supports purchasing, sales, inventory, finance, production, costs, assets, auditing, workflow, and metadata operations.-