金蝶云星空 MCP 连接器

技能文档

---
name: kingdee-mcp-connector
title: 金蝶云星空 MCP 连接器
category: 开发工具
description: 连接并配置金蝶云星空 MCP Server，将金蝶 ERP 接入当前 Agent 环境。接入后可用自然语言查询和操作金蝶 ERP 单据，覆盖采购、销售、库存、生产、成本、固定资产等业务域。当用户想「连接金蝶」「配置金蝶 MCP」「接入金蝶 ERP」「用 AI 操作金蝶」时触发。
---

# 金蝶云星空 MCP 连接器

> 第三方开源项目（GitHub: [WaHaiLong/KingdeeMCP](https://github.com/WaHaiLong/KingdeeMCP)，PyPI: `kingdee-mcp`），非金蝶官方出品。与金蝶软件公司无隶属、无授权关系。对外文案不得标注"金蝶官方""官方技术号"等表述。

本技能将社区开发的金蝶云星空 MCP Server 接入当前 Agent 环境。接入后，用户可在对话中说"查询本月已审核的采购订单""帮我新建一张销售订单""审核这几张入库单"等，Agent 自动调用金蝶 WebAPI 完成操作。

完整工具列表、支持的 form_id、环境变量与常见问题见 `references/kingdee_reference.md`。

## 技能工作流

### 步骤1：前置检查

- 确认用户机器已安装 `uv`（推荐，用于 `uvx kingdee-mcp` 免安装运行）。未安装时：macOS/Linux 用 `brew install uv`，或 `pip install uv`。
- 备用方案（未装 uv）：执行 `pip install kingdee-mcp`，之后 MCP 启动命令改用 `python -m kingdee_mcp.server`（见步骤3）。

### 步骤2：收集金蝶连接参数

向用户索取以下 4 个必填项（金蝶云星空账号，建议用专用集成账号，**不要用 Administrator**）：

1. `KINGDEE_SERVER_URL` — 金蝶服务器地址，**必须包含 `/k3cloud/` 后缀**，如 `http://your-server/k3cloud/`
2. `KINGDEE_ACCT_ID` — 账套 ID
3. `KINGDEE_USERNAME` — 金蝶账号（建议专用集成账号，非 Administrator）
4. `KINGDEE_PASSWORD` — 金蝶账号密码（采用账号密码 ValidateUser 登录，**无需 AppID/AppSecret**）

可选（SQL Server 数据库探查，用于理解金蝶库表结构）：`MCP_SQLSERVER_HOST / PORT / DATABASE / USER / PASSWORD`。

> 登录方式为「账号密码(ValidateUser)」，无需在金蝶后台创建第三方应用，也无需 AppID/AppSecret。该账号需分配对应模块的操作权限。详见 `references/kingdee_reference.md`。

### 步骤3：写入 MCP 配置

运行本技能附带的配置脚本，将金蝶 MCP 合并写入 MCP 配置文件（保留已有其他 server 配置）：

```bash
python3 scripts/configure_kingdee_mcp.py \
  --server-url "http://your-server/k3cloud/" \
  --acct-id "你的账套ID" \
  --username "金蝶账号" \
  --password "金蝶账号密码"
```

脚本会读取（不存在则新建）本地 MCP 配置文件，在 `mcpServers` 下写入：

```json
{
  "mcpServers": {
    "kingdee": {
      "command": "uvx",
      "args": ["kingdee-mcp"],
      "env": {
        "KINGDEE_SERVER_URL": "...",
        "KINGDEE_ACCT_ID": "...",
        "KINGDEE_USERNAME": "...",
        "KINGDEE_PASSWORD": "..."
      }
    }
  }
}
```

> 未安装 uv 的用户：将上面 `command` 改为 `"python"`、`args` 改为 `["-m", "kingdee_mcp.server"]`（前提是已 `pip install kingdee-mcp`）。配置脚本默认按 uvx 写入，写完后可手动调整该条目。

### 步骤4：信任与启用

写入配置后，告知用户：
- 在 MCP 连接器管理页面找到 `kingdee` 这个 server，点击「信任 / 启用」。
- 重启 Agent 或重连 MCP，使配置生效。

### 步骤5：验证

建议用户在对话中测试一句自然语言，例如「查询最近 20 条已审核的采购订单」，确认 Agent 能调用金蝶工具并返回结果。若认证失败，检查金蝶账号与密码(KINGDEE_PASSWORD)是否正确、该账号是否有对应模块的操作权限；若连接超时，检查 `KINGDEE_SERVER_URL` 是否含 `/k3cloud/` 且服务器可访问（详见 `references/kingdee_reference.md` 的 FAQ）。

## 安全提示

- 金蝶账号密码属敏感凭据，仅写入本地配置文件，不要外泄或提交到公开仓库。
- 金蝶集成用户应使用专用账号，分配最小必要权限，不要用 Administrator。

## 资源清单

- `scripts/configure_kingdee_mcp.py` — 将金蝶 MCP 配置合并写入 MCP 配置文件的脚本。
- `references/kingdee_reference.md` — 完整工具列表、支持的单据类型（form_id）、环境变量说明、后台授权步骤与常见问题。

使用说明

# 金蝶云星空 MCP 连接器

用自然语言查询和操作金蝶云星空 ERP 单据，覆盖采购、销售、库存、生产、成本、固定资产等 13 个业务域、87 个工具。

## 使用

在对话中直接说：

```
连接金蝶
```

按提示提供金蝶服务器地址、账套 ID、账号和密码，脚本自动完成 MCP 配置。配置生效后即可用自然语言操作金蝶：

```
查询本月已审核的采购订单
帮我新建一张销售订单
审核这几张入库单
```

## 工作原理

本技能将第三方开源项目 [KingdeeMCP](https://github.com/WaHaiLong/KingdeeMCP)（PyPI: `kingdee-mcp`）接入 Agent 的 MCP 配置。通过金蝶 WebAPI 以账号密码方式登录，支持 87 个工具覆盖通用单据、生产制造、成本核算、固定资产、库存、审计合规等业务场景。

## 前置要求

- 金蝶云星空账号（建议专用集成账号，非 Administrator）
- `uv`（推荐）或 `pip`（用于安装 kingdee-mcp）

## 安全提示

- 账号密码仅写入本地配置文件，不会上传
- 建议使用专用集成账号，分配最小必要权限

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。