Kingdee K3Cloud ERP MCP Server

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.

GitHub

Documentation

Kingdee K3Cloud MCP

English | 中文

PyPI version Python License CI

金蝶云星空 K3Cloud MCP Server，让 AI 助手（Claude Desktop、Claude Code、Cursor、Cline、Cherry Studio、Openclaw 等任意支持 MCP 协议的客户端）通过自然语言查询和操作金蝶 ERP 系统。

提示：支持 Skill 机制的 AI Agent（Claude Code、openclaw、hermes 等）可配合 kingdee-k3cloud-skill 获得更佳体验。Skill 为 Agent 注入金蝶表单字段、常用查询模式和工作流知识，大幅减少试错次数。

┌─────────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
│  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 the Model Context Protocol.

功能特性

  • 15 个 MCP 工具：覆盖查询、大数据量导出、新增、提交、审核、反审核、删除、下推等核心操作
  • 通用接口设计：单一 form_id 参数支持物料、客户、销售订单、采购订单等所有表单，无需为每种业务单独配置
  • 高阶查询原语：query_bill_all（自动翻页）、query_bill_to_file（流式落盘）、query_bill_range（日期分片），彻底消除模型手动循环的负担
  • 只读/读写模式：可限制 AI 只能查询，防止误操作
  • 自动会话恢复：长时间运行时自动处理会话超时，无需人工干预
  • 多传输协议：支持 stdio（本地）、SSE、streamable-http（远程共享）

快速开始

方式一：uvx 直接运行（推荐）

无需克隆仓库，直接通过 uvx 运行。注意：服务启动时必须提供 5 个必填环境变量（KD_SERVER_URL、KD_ACCT_ID、KD_USERNAME、KD_APP_ID、KD_APP_SEC），否则会报错退出。

在 MCP 客户端中使用（推荐，见下方"客户端配置"章节）：通过客户端配置的 env 字段传入，uvx 进程会自动读取。

手动测试时，可通过以下任一方式提供环境变量：

# 方式 A：在当前目录创建 .env 文件（服务启动时自动加载）
cp .env.example .env   # 填写真实值后再运行
uvx 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
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

配置

复制环境变量模板并填写：

cp .env.example .env
环境变量说明示例
KD_SERVER_URL金蝶服务器地址（必须以 /k3cloud/ 结尾）https://your-server/k3cloud/
KD_ACCT_ID账套 IDyour_acct_id
KD_USERNAME集成用户账号your_username
KD_APP_ID应用 IDyour_app_id
KD_APP_SEC应用密钥your_app_secret
KD_LCID语言（默认 2052 中文）2052
KD_ORG_NUM组织编码（可选）

第三方应用 ID 和密钥需在金蝶云星空管理端的「第三方系统登录授权」中申请。

环境变量配置说明

在金蝶云星空产品中配置第三方系统集成，需按以下步骤获取 5 个环境变量：

1. 登录金蝶云星空管理后台

  1. 使用管理员账号登录金蝶云星空系统，进入「系统管理」菜单下的「第三方系统登录授权」。
  2. 点击新增按钮，进入新增第三方系统登录授权功能页面。
  3. 点击”获取应用 ID”按钮，根据提示跳转到 Open 网站 的第三方系统登录授权页面，点击“新增授权”。
  4. Open 网站用户根据自身信息进行表单填写。
  5. 提交成功后会生成应用信息，复制应用信息填入金蝶云星空产品 - 第三方系统登录授权 - 获取应用 ID - 应用信息框中，点击“确认”按钮。
  6. 配置集成用户。
  7. 点击“保存”按钮，保存成功后点击“生成测试链接”，测试链接是否成功。

注意：当前数据库中心 ID（即账套 ID）可以通过生成测试链接弹出的信息中获取。

2. 获取 KD_SERVER_URL

金蝶服务器地址，格式为 https://your-server/k3cloud/，其中：

  • your-server 为金蝶云星空服务器的域名或 IP 地址
  • 一般以 /k3cloud/ 结尾
  • 示例：https://erp.company.com/k3cloud/

3. 获取 KD_ACCT_ID - 账套 ID

4. 获取 KD_USERNAME - 集成用户账号

使用具有相关模块操作权限的账号，不建议使用管理员账号。建议新建一个专门的集成用户账号，并为其分配所需的模块操作权限。

5. 获取 KD_APP_ID - 应用 ID 和 KD_APP_SEC - 应用密钥

注意：如需查看 APP_SECRET，可随时在应用详情中查看；如遗失，也可通过「重置」功能重新生成。

6. 验证配置

配置完成后，可通过以下命令验证连接：

cd kingdee-k3cloud-mcp
cp .env.example .env
# 编辑 .env 填写上述 5 个环境变量
uvx kingdee-k3cloud-mcp

如看到「MCP Server running」或类似输出，表示配置成功。

参考文档：金蝶云星空第三方系统集成配置指南

客户端配置

Claude Desktop

编辑 ~/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"
      }
    }
  }
}

Claude Code

在项目目录下创建 .mcp.json：

{
  "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 / Windsurf 及其他 MCP 客户端

配置方式与 Claude Desktop 类似，参考各客户端的 MCP 配置文档，使用相同的 uvx 命令和环境变量。

SSE 模式（远程共享）

如需多人共用同一个服务实例：

# 启动 SSE 服务（默认端口 8000）
FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=8080 uvx kingdee-k3cloud-mcp --transport sse

客户端连接地址：http://your-server:8080/sse

可通过 MCP_API_KEY 环境变量启用 Bearer Token 鉴权。

可用工具

查询工具（只读模式下可用）

工具说明
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查询表单字段结构（元数据）

写入工具（读写模式下可用）

工具说明
save_bill保存/新增单据
submit_bill提交单据
audit_bill审核单据
unaudit_bill反审核单据
delete_bill删除单据
execute_operation执行自定义操作（禁用、反禁用等）
push_bill下推单据（如销售订单→发货通知单）

所有工具通过 form_id 参数支持任意表单（物料、客户、供应商、销售订单、采购订单等）。

只读模式

通过 --mode readonly 或 MCP_MODE=readonly 限制服务器只暴露 8 个查询工具，防止 AI 误操作写入数据。

"args": ["kingdee-k3cloud-mcp", "--mode", "readonly"]

或：

"env": {
  "MCP_MODE": "readonly",
  ...
}

调试

使用 MCP Inspector 可视化调试工具：

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 工具。

为什么选择 MCP 而非直接调用？

让 AI 直接通过 Skill 构造 HTTP 请求访问 ERP，技术上可行，但会引入一系列安全隐患。MCP 的进程隔离模型从根本上解决了这些问题。

凭证不进入 LLM 上下文

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 的权限模型所限定，而不是依赖模型的"自觉"。

配套 Skill（支持 Skill 的 Agent）

kingdee-k3cloud-skill 是面向支持 Skill 机制的 AI Agent（Claude Code、openclaw、hermes 等）的配套 Skill，提供：

  • 常用表单 ID 速查表（BD_MATERIAL、SAL_SaleOrder 等）
  • 已验证字段名列表（避免字段名错误导致 500）
  • 日报、客户查询、销售分析、库存分析、订单追踪等完整工作流

安装后 Agent 可自动掌握金蝶 ERP 的正确查询方式，无需反复试错。

开发

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

安装 pre-commit hooks（可选，与 CI 保持一致）：

uv run pre-commit install

贡献者

Contributors

Made with contrib.rocks.

许可证

Apache License 2.0 — 详见 LICENSE