Kingdee K3cloud Mcp

金蝶MCP Server（Kingdee K3Cloud MCP）面向金蝶云星空 ERP，让 AI 助手（Claude Desktop、Claude Code、Cursor、Windsurf、Cline、Continue、Cherry Studio 等任意支持 MCP 协议的客户端）通过自然语言查询和操作金蝶 ERP 系统。标准 PyPI 包，pip install 或 uvx 均可直接运行，无需绑定特定包管理器。

提示：通过 Openclaw 等支持 MCP 的 Agent 平台接入后，可在其支持的 IM 渠道（如微信、Telegram）中用自然语言查库存、查单据，无需打开金蝶网页端。支持 Skill 机制的 AI Agent（Claude Code、Openclaw 等）还可配合 kingdee-k3cloud-skill 获得更佳体验——Skill 为 Agent 注入金蝶表单字段、常用查询模式和工作流知识，大幅减少试错次数，但并非必需，MCP Server 本身即可独立配合任意 MCP 客户端使用全部工具。

┌─────────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
│  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（远程共享）
标准 Python 包：pip install 即可安装，仅需 Python 3.10+，无强制包管理器依赖
类型安全的入参校验：所有工具入参基于类型注解，由 FastMCP 在调用时自动做 Pydantic 运行时校验，参数结构错误会在到达金蝶 API 之前被拦截

5 分钟快速开始

安装：pip install kingdee-k3cloud-mcp（或用 uvx kingdee-k3cloud-mcp 免安装直接跑）
在金蝶云星空「第三方系统登录授权」中申请应用 ID/密钥，拿到 5 个必填环境变量（见下方配置）
把变量填进你的 MCP 客户端配置（见下方客户端配置），保存重启
直接用自然语言提问，例如：
- 「查一下上周已审核的销售订单，按金额排序」
- 「XX 物料现在各仓库库存分别是多少」
- 「把 3 月份所有销售出库单导出成 csv」

快速开始

方式一：pip 安装（推荐，无需 uv）

pip install kingdee-k3cloud-mcp
kingdee-k3cloud-mcp

标准 PyPI 包，仅需 Python 3.10+，不依赖 uv。注意：服务启动时必须提供 5 个必填环境变量（KD_SERVER_URL、KD_ACCT_ID、KD_USERNAME、KD_APP_ID、KD_APP_SEC），否则会报错退出。

在 MCP 客户端中使用（推荐，见下方"客户端配置"章节）：通过客户端配置的 env 字段传入。

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

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

方式二：uvx 直接运行（免安装）

无需 pip install，uvx 会自动创建隔离环境并运行，用法与上面完全一致，把 kingdee-k3cloud-mcp 换成 uvx kingdee-k3cloud-mcp 即可：

cp .env.example .env
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