Kingdee K3Cloud MCP — 让 AI 助手直连金蝶云星空

功能特性

Features

为真实 ERP 场景而设计

Built for real-world ERP workloads

不止是 API 转发 —— 内置大数据量导出、日期分片、只读模式和会话自愈能力。

More than an API wrapper — built-in bulk export, date sharding, read-only mode, and self-healing sessions.

🧰

15 个 MCP 工具

15 MCP Tools

覆盖查询、导出、新增、提交、审核、反审核、删除、下推等核心操作。

Covers query, export, create, submit, audit, unaudit, delete, and push operations.

🧩

通用接口设计

Universal Interface

单一 form_id 参数支持物料、客户、销售订单等所有表单。

A single form_id parameter drives every form — materials, customers, sales orders, and more.

📈

高阶查询原语

High-level Query Primitives

query_bill_all 自动翻页、query_bill_to_file 流式落盘、query_bill_range 日期分片。

Auto-pagination, streaming file export, and date-range sharding — no manual loops.

🔒

只读 / 读写模式

Read-only / Read-write Modes

可限制 AI 只能查询，从工具列表层面物理防止误操作。

Restrict the AI to queries only — write tools are physically absent from the tool list.

♻️

自动会话恢复

Automatic Session Recovery

长时间运行时自动处理会话超时，无需人工干预。

Handles session timeouts automatically during long-running operations.

🌐

多传输协议

Multiple Transports

支持 stdio（本地）、SSE、streamable-http（远程共享）。

Supports stdio (local), SSE, and streamable-http (shared remote deployment).

工具参考

Tools Reference

可用工具一览

Available Tools

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

Every tool accepts a form_id parameter, so one tool works across all forms.

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

Query Tools (available in read-only mode)

工具	Tool	说明
query_bill	查询单据数据（返回二维数组）	Query bill data (returns 2D array)
query_bill_json	查询单据数据（返回 JSON，字段名作为 key）	Query bill data as JSON, keyed by field name
count_bill	估算查询结果行数，用于大数据量查询前的探测	Estimate row count before a large query
query_bill_all	自动翻页查询直到拉完或达到安全上限	Auto-paginate until complete or a safety cap
query_bill_to_file	自动翻页并流式写入本地文件（ndjson / csv）	Auto-paginate and stream to a local file (ndjson / csv)
query_bill_range	按日期自动分片（月/周/日）+ 翻页	Auto date-sharding (month/week/day) + pagination
view_bill	查看单条记录完整详情	View full detail of a single record
query_metadata	查询表单字段结构（元数据）	Query form field structure (metadata)

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

Write Tools (available in read-write mode)

工具	Tool	说明
save_bill	保存 / 新增单据	Save / create a bill
submit_bill	提交单据	Submit a bill
audit_bill	审核单据	Audit a bill
unaudit_bill	反审核单据	Unaudit a bill
delete_bill	删除单据	Delete a bill
execute_operation	执行自定义操作（禁用、反禁用等）	Execute a custom operation (forbid/unforbid, etc.)
push_bill	下推单据（如销售订单→发货通知单）	Push a bill downstream (e.g. sales order → delivery notice)

安装指南

Installation

四步接入

Four steps to connect

通过 uvx 直接运行

Run directly with uvx

无需克隆仓库：uvx kingdee-k3cloud-mcp

No cloning required: uvx kingdee-k3cloud-mcp

申请金蝶后台授权

Authorize on the Kingdee backend

在「第三方系统登录授权」中申请应用 ID 和密钥，获取 5 个必填环境变量。

配置 MCP 客户端

Configure your MCP client

在 claude_desktop_config.json 或项目 .mcp.json 中添加 server 配置。

Add the server entry to claude_desktop_config.json or your project's .mcp.json.

重启客户端

Restart the client

重启后即可用自然语言查询和操作金蝶数据。

Restart, then query and operate Kingdee data in natural language.

// claude_desktop_config.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"
      }
    }
  }
}

设计理念

Design Rationale

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

Why MCP instead of direct API calls?

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

Letting the AI build raw HTTP requests via a Skill is technically possible — but risky. MCP's process-isolation model fixes this at the root.

凭证不进入 LLM 上下文

Credentials never enter the LLM context

凭证通过环境变量注入独立进程，模型永远看不到。

Credentials are injected via env vars into an isolated process — the model never sees them.

强制权限边界，而非依赖提示词

Enforced boundaries, not prompt promises

--mode readonly 是物理限制：写入工具根本不在工具列表中。

--mode readonly is a physical restriction — write tools simply don't exist in the tool list.

网络隔离

Network isolation

Server 部署在内网直连 ERP，LLM 云端运行，从不直接接触内部网络。

The server runs inside your network; the LLM never touches it directly.

完整的审计链路

Full audit trail

每次工具调用都经过 Server，可统一记录操作、参数、时间戳与来源。

Every call passes through the server, enabling unified logging of operation, params, and timestamp.

最小权限原则

Principle of least privilege

集成用户可在金蝶系统内限制模块与只读权限，MCP Server 原样继承。

Kingdee-side user permissions carry straight through — the LLM never needs to know the boundary exists.

FAQ

常见问题

Frequently Asked Questions

会话超时怎么处理？How are session timeouts handled?

Server 内置自动会话恢复机制，长时间运行时检测到超时会自动重新登录，无需人工干预。

The server automatically re-authenticates on timeout during long-running sessions — no manual action needed.

只读模式如何开启？How do I enable read-only mode?

通过 --mode readonly 参数或 MCP_MODE=readonly 环境变量，服务器只暴露 8 个查询工具。

Pass --mode readonly or set MCP_MODE=readonly — only the 8 query tools are exposed.

可以多人共用一个 Server 实例吗？Can multiple users share one server instance?

可以，使用 SSE 或 streamable-http 传输部署为远程共享服务，并可通过 MCP_API_KEY 启用鉴权。

Yes — deploy with SSE or streamable-http transport, and enable auth via MCP_API_KEY.

如何扩展支持更多单据类型？How do I support more bill types?

所有工具通过通用的 form_id 参数工作，无需为新单据类型单独开发工具，直接传入对应 form_id 即可。

All tools take a generic form_id — just pass the target form's ID, no new tool needed.

数据量很大时怎么导出？How do I export large datasets?

使用 query_bill_to_file 自动翻页并流式写入本地文件（ndjson / csv），适合万行以上导出。

Use query_bill_to_file to auto-paginate and stream results to a local file — suited for 10k+ rows.

和 kingdee-k3cloud-skill 是什么关系？How does this relate to kingdee-k3cloud-skill?

Skill 负责"什么时候用、怎么用"的知识注入（表单速查、字段验证、工作流），MCP Server 负责实际的工具执行。支持 Skill 机制的 AI Agent（Claude Code、openclaw、hermes 等）配合使用效果更佳。

The Skill injects domain knowledge (form lookups, verified fields, workflows); the MCP server executes the tools. Best combined with any Skill-capable agent, such as Claude Code, openclaw, or hermes.

兼容所有 MCP 协议客户端

Works with any MCP client