金蝶MCP Server｜金蝶云星空 K3Cloud MCP

功能特性

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.

🩺

认证失败诊断

Authentication Diagnostics

启动即校验凭据，认证失败返回可操作的修复指引，而不是误导文案。

Credentials are verified at startup; auth failures return actionable remediation, not a misleading message.

🌐

多传输协议

Multiple Transports

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

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

📦

标准 Python 包

Standard Python Package

pip install 即可安装，仅需 Python 3.10+，无强制包管理器依赖。

Install with pip install, Python 3.10+ only — no mandatory package manager.

🛡️

类型安全校验

Type-safe Validation

工具入参基于类型注解，由 FastMCP 自动做 Pydantic 运行时校验。

Tool arguments are type-annotated and validated at call time via FastMCP's automatic Pydantic runtime checks.

工具参考

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

安装

Install

pip install kingdee-k3cloud-mcp，或免安装直接跑：uvx kingdee-k3cloud-mcp。

pip install kingdee-k3cloud-mcp, or run without installing: 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"
      }
    }
  }
}

装好之后

Once it's running

"查一下上周已审核的销售订单，按金额排序"
"Show me last week's audited sales orders, sorted by amount"
"XX 物料现在各仓库库存分别是多少"
"What's the current stock of material XX across all warehouses?"
"把 3 月份所有销售出库单导出成 csv"
"Export all March sales outbound bills to CSV"

设计理念

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

金蝶MCP 是什么？和金蝶官方的 MCP 有什么关系？What is Kingdee MCP, and how does it relate to Kingdee's official MCP?

「金蝶MCP」通常指两件不同的事。一是金蝶官方：金蝶宣布云·苍穹平台支持 MCP 协议，属于官方商业产品线。二是本项目：面向金蝶云星空（K3Cloud）的第三方开源 MCP Server，基于官方 kingdee-cdp-webapi-sdk 调用 K3Cloud Web API，用 Apache-2.0 协议发布在 PyPI 上，可自行部署、连接你自己的星空账套，与金蝶官方无隶属关系。如果你用的是云星空且想让 Claude、Cursor 这类 AI 客户端直接读写单据，本项目就是为这个场景做的。

"Kingdee MCP" can mean two different things. One is Kingdee's own offering — Kingdee announced MCP protocol support for its Cangqiong (苍穹) platform, a commercial product line. The other is this project: a third-party, open-source MCP Server for Kingdee K3Cloud (金蝶云星空), built on the official kingdee-cdp-webapi-sdk against the K3Cloud Web API, published on PyPI under Apache-2.0. It is self-hosted, connects to your own K3Cloud account set, and is not affiliated with Kingdee. If you run K3Cloud and want Claude, Cursor, or similar AI clients to read and write bills directly, this is the project for that.

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

不需要处理：实测确认会话过期对调用方是无感的，金蝶服务端会静默换发新会话，请求照常成功。需要注意的是金蝶那句「会话信息已丢失，请重新登录」并不是会话过期，而是认证失败——重试无效，Server 会把它替换为带修复步骤的诊断信息，指出该核对哪几项凭据配置。

Nothing to handle: session expiry is transparent — K3Cloud silently issues a new session and the request succeeds. Note that Kingdee's "session lost, please log in again" message is not a session expiry but an authentication failure, where retrying cannot help; the server replaces it with a diagnostic naming the exact credential settings to check.

只读模式如何开启？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.

必须用 uv 吗？Do I have to use uv?

不需要。这是一个标准 PyPI 包，pip install kingdee-k3cloud-mcp 即可安装运行，仅需 Python 3.10+。uvx 只是一种免安装的可选便捷方式，不是必须依赖。

No. It's a standard PyPI package — pip install kingdee-k3cloud-mcp works with just Python 3.10+. uvx is an optional install-free convenience, not a requirement.

必须安装配套 Skill 吗？Do I have to install the companion Skill?

不需要。MCP Server 独立运行即可使用全部 15 个工具，且内置 query_metadata 让 AI 自行发现表单字段。Skill 是可选增强，能进一步减少字段试错、封装企业自定义字段和工作流知识，配合支持 Skill 机制的 Agent（如 Claude Code、Openclaw）效果更佳。

No. The MCP server works standalone with all 15 tools, and includes query_metadata so the AI can discover form fields itself. The Skill is an optional enhancement that further reduces trial-and-error and encodes your custom fields/workflows — best combined with Skill-capable agents like Claude Code or Openclaw.

数据权限怎么设置？How do I configure data permissions?

权限不在 MCP 配置中设置，由 KD_USERNAME 对应的集成用户在金蝶云星空侧的角色决定。注意数据规则过滤是静默的——结果行数变少而非报错，可用同一账号登录星空 Web 端对比行数确认，详见 README「数据权限」一节。

Permissions aren't configured on the MCP side — they're determined by the integration user (KD_USERNAME)'s role in K3Cloud. Note that data-rule filtering is silent (fewer rows, no error); compare against the K3Cloud web UI with the same account to confirm. See the "Data Permissions" section in the README.

可以多人共用一个 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