Skip to main content
Glama
kingdee-mcp

kingdee-mcp

by YanSir1999

Kingdee MCP

English | 中文

金蝶云星空(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:

变量

必填

说明

KD_SERVER_URL

是

金蝶地址,建议以 /k3cloud/ 结尾

KD_ACCT_ID

是

账套 ID

KD_USERNAME

是

集成用户账号

KD_PASSWORD

建议

密码(ValidateUser 登录)

FASTMCP_HOST

否

SSE 监听地址;Docker/CLB 用 0.0.0.0

FASTMCP_PORT

否

SSE 端口,默认 8181

MCP_MODE

否

readonly(默认)或 readwrite

MCP_API_KEY

否

SSE/HTTP Bearer Token;不设则不鉴权

MCP_ISSUER_URL

否

鉴权元数据对外 URL(启用 MCP_API_KEY 时)

MCP_ALLOWED_HOSTS

否

SSE Host 白名单,逗号分隔;解决远程 421 Invalid Host header

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)

工具

说明

query_bill

查询单据(二维数组)

query_bill_json

查询单据(JSON,字段名为 key)

count_bill

估算行数

query_bill_all

自动翻页拉取

query_bill_to_file

翻页流式落盘(ndjson/csv)

query_bill_range

按日期分片 + 翻页

view_bill

单条详情

query_metadata

表单元数据

写入工具(仅 readwrite)

工具

说明

save_bill

保存/新增

submit_bill

提交

audit_bill

审核

unaudit_bill

反审核

delete_bill

删除

execute_operation

自定义操作(禁用/反禁用等)

push_bill

下推

常用 form_id 示例:

FormId

说明

BD_MATERIAL

物料

BD_Customer

客户

BD_Supplier

供应商

SAL_SaleOrder

销售订单

PUR_PurchaseOrder

采购订单

PRD_MO

生产订单

STK_InStock / STK_OutStock

入/出库单

只读模式

默认 MCP_MODE=readonly(或 --mode readonly):

  1. 写入工具从 MCP 工具列表中移除

  2. 即使被直接调用,也会返回 只读模式:写入操作已禁用

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。

许可证

Apache License 2.0

Available Tools

8 tools
count_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

    B3/5.0

    Scored across 8 tools

    Disambiguation2/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      MCP server for Kingdee K3Cloud ERP that enables AI assistants to query and operate ERP data via natural language through the Model Context Protocol.
      15
      409 PyPI
      104
      Apache 2.0
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -