Kingdee K3Cloud ERP

Servidor MCP para Kingdee K3Cloud (金蝶云星空) — uno de los sistemas ERP más utilizados en China. Conecta asistentes de IA (Claude Desktop, Cursor, Cline, Cherry Studio, etc.) al ERP de Kingdee mediante lenguaje natural.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de Kingdee (Kingdee K3Cloud MCP)

English | 中文

Sitio web oficial de Kingdee MCP | GitHub | PyPI

El Servidor MCP de Kingdee (Kingdee K3Cloud MCP) está orientado a Kingdee Cloud Galaxy ERP, y permite que asistentes de IA (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, Cherry Studio, o cualquier otro cliente compatible con el protocolo MCP) consulten y operen el sistema ERP de Kingdee mediante lenguaje natural. Es un paquete estándar de PyPI; se puede ejecutar directamente con pip install o uvx, sin necesidad de estar vinculado a un gestor de paquetes específico.

Nota: Al integrarlo a través de plataformas de agentes compatibles con MCP como Openclaw, podrás consultar inventarios y documentos mediante lenguaje natural en los canales de mensajería compatibles (como WeChat o Telegram), sin necesidad de abrir la interfaz web de Kingdee. Los agentes de IA con mecanismo de Skills (Claude Code, Openclaw, etc.) también pueden combinarse con kingdee-k3cloud-skill para una mejor experiencia: el Skill inyecta al agente el conocimiento de los campos de formularios de Kingdee, patrones de consulta comunes y flujos de trabajo, reduciendo considerablemente los intentos de prueba y error, aunque no es imprescindible: el propio Servidor MCP puede funcionar de forma independiente con cualquier cliente MCP y usar todas sus herramientas.

┌─────────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
│  kingdee-k3cloud    │───▶│  kingdee-k3cloud    │───▶│  K3Cloud Web API │
│  -skill             │    │  -mcp               │    │  (金蝶云星空)     │
│  知识库 / 工作流     │    │  执行引擎 / MCP工具  │    │                  │
└─────────────────────┘    └─────────────────────┘    └──────────────────┘
      支持 Skill 的 Agent          所有 MCP 客户端通用

Servidor MCP para Kingdee K3Cloud ERP. Conecta asistentes de IA a tu sistema ERP mediante el Protocolo de Contexto de Modelo.

Características

15 herramientas MCP: cubren operaciones clave como consulta, exportación de grandes volúmenes de datos, creación, envío, aprobación, desaprobación, eliminación y empuje descendente.
Diseño de interfaz universal: un único parámetro form_id admite todos los formularios (materiales, clientes, pedidos de venta, pedidos de compra, etc.), sin necesidad de configuraciones específicas por negocio.
Primitivas de consulta avanzadas: query_bill_all (paginación automática), query_bill_to_file (escritura en streaming a disco), query_bill_range (fragmentación por fechas), eliminando por completo la carga de bucles manuales del modelo.
Modo solo lectura / lectura-escritura: permite restringir la IA a solo consultas, evitando operaciones accidentales.
Diagnóstico de fallos de autenticación: valida las credenciales al iniciar; si hay errores de credenciales o configuración de autorización, devuelve instrucciones de corrección accionables, en lugar del engañoso mensaje de Kingdee «información de sesión perdida».
Múltiples protocolos de transporte: soporta stdio (local), SSE y streamable-http (compartido remoto).
Paquete estándar de Python: se instala con pip install, solo requiere Python 3.10+, sin dependencia obligatoria de un gestor de paquetes.
Validación de parámetros de entrada con seguridad de tipos: todos los parámetros de las herramientas se basan en anotaciones de tipos, y FastMCP realiza la validación en tiempo de ejecución con Pydantic al invocarlas; los errores estructurales de parámetros se interceptan antes de llegar a la API de Kingdee.

Inicio rápido en 5 minutos

Instalación: pip install kingdee-k3cloud-mcp (o usa uvx kingdee-k3cloud-mcp para ejecutarlo sin instalación).
Solicita el ID/Secreto de aplicación en «Autorización de inicio de sesión de sistemas de terceros» de Kingdee Cloud Galaxy y obtén las 5 variables de entorno obligatorias (ver Configuración más abajo).
Introduce las variables en la configuración de tu cliente MCP (ver Configuración del cliente más abajo), guarda y reinicia.
Haz preguntas directamente en lenguaje natural, por ejemplo:
- «Consulta los pedidos de venta aprobados de la semana pasada, ordenados por importe».
- «¿Cuál es el inventario actual de cada almacén para el material XX?».
- «Exporta todos los albaranes de venta de marzo a CSV».

Inicio rápido

Opción 1: Instalación con pip (recomendada, sin necesidad de uv)

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

Paquete estándar de PyPI, solo requiere Python 3.10+, sin dependencia de uv. Nota: al iniciar el servicio, es obligatorio proporcionar las 5 variables de entorno (KD_SERVER_URL, KD_ACCT_ID, KD_USERNAME, KD_APP_ID, KD_APP_SEC); de lo contrario, se producirá un error y se cerrará.

Uso en un cliente MCP (recomendado; ver la sección «Configuración del cliente» más abajo): se pasan mediante el campo env de la configuración del cliente.

Para pruebas manuales, puedes proporcionar las variables de entorno de cualquiera de las siguientes formas:

# 方式 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

Opción 2: Ejecución directa con uvx (sin instalación)

Sin necesidad de pip install; uvx creará automáticamente un entorno aislado y lo ejecutará. El uso es exactamente igual al anterior; solo cambia kingdee-k3cloud-mcp por uvx kingdee-k3cloud-mcp:

cp .env.example .env
uvx kingdee-k3cloud-mcp

Opción 3: Ejecución desde el código fuente

git clone https://github.com/adamzhang1987/kingdee-k3cloud-mcp.git
cd kingdee-k3cloud-mcp
uv sync
uv run kingdee-k3cloud-mcp

Configuración

Copia la plantilla de variables de entorno y complétala:

cp .env.example .env

Variable de entorno	Descripción	Ejemplo
`KD_SERVER_URL`	Dirección del servidor de Kingdee (debe terminar en `/k3cloud/`)	`https://your-server/k3cloud/`
`KD_ACCT_ID`	ID del conjunto de cuentas	`your_acct_id`
`KD_USERNAME`	Cuenta de usuario de integración	`your_username`
`KD_APP_ID`	ID de aplicación	`your_app_id`
`KD_APP_SEC`	Secreto de aplicación	`your_app_secret`
`KD_LCID`	Idioma (por defecto 2052, chino)	`2052`
`KD_ORG_NUM`	Código de organización (opcional)
`KD_STARTUP_CHECK`	Validar credenciales al iniciar (activado por defecto; `0` para desactivar)	`1`
`KD_STARTUP_CHECK_TIMEOUT`	Tiempo de espera en segundos para la autocomprobación al iniciar (por defecto 5)	`5`

El ID y el secreto de la aplicación de terceros deben solicitarse en «Autorización de inicio de sesión de sistemas de terceros» del panel de administración de Kingdee Cloud Galaxy.

Notas sobre la configuración de variables de entorno

Para configurar la integración de sistemas de terceros en Kingdee Cloud Galaxy, sigue estos pasos para obtener las 5 variables de entorno:

1. Inicia sesión en el panel de administración de Kingdee Cloud Galaxy

Inicia sesión en Kingdee Cloud Galaxy con una cuenta de administrador y ve a «Autorización de inicio de sesión de sistemas de terceros» dentro del menú «Administración del sistema».
Haz clic en el botón «Nuevo» para acceder a la página de nueva autorización de inicio de sesión de sistemas de terceros.
Haz clic en el botón «Obtener ID de aplicación» y, según las indicaciones, ve a la página de autorización de inicio de sesión de sistemas de terceros del sitio web Open y haz clic en «Nueva autorización».
El usuario del sitio web Open completa el formulario con su información.
Tras enviarlo correctamente, se generará la información de la aplicación. Cópiala y pégala en el campo «Información de la aplicación» de «Obtener ID de aplicación» en Kingdee Cloud Galaxy, y haz clic en «Confirmar».
Configura el usuario de integración.
Haz clic en «Guardar»; tras guardar correctamente, haz clic en «Generar enlace de prueba» para comprobar si el enlace funciona.

Nota: el ID del centro de base de datos actual (es decir, el ID del conjunto de cuentas) se puede obtener de la información que aparece al generar el enlace de prueba.

2. Obtener KD_SERVER_URL

Dirección del servidor de Kingdee, con formato https://your-server/k3cloud/, donde:

your-server es el nombre de dominio o la dirección IP del servidor de Kingdee Cloud Galaxy.
Generalmente termina en /k3cloud/.
Ejemplo: https://erp.company.com/k3cloud/.

3. Obtener KD_ACCT_ID: ID del conjunto de cuentas

4. Obtener KD_USERNAME: cuenta de usuario de integración

Usa una cuenta con permisos de operación sobre los módulos relevantes. No se recomienda usar una cuenta de administrador. Se sugiere crear una cuenta de integración dedicada y asignarle los permisos de operación necesarios.

5. Obtener KD_APP_ID: ID de aplicación y KD_APP_SEC: secreto de aplicación

Nota: si necesitas ver el APP_SECRET, puedes consultarlo en cualquier momento en los detalles de la aplicación; si lo pierdes, también puedes regenerarlo mediante la función «Restablecer».

6. Verificar la configuración

Una vez configurado, puedes verificar la conexión con el siguiente comando:

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

Si ves «MCP Server running» o una salida similar, la configuración es correcta.

Documentación de referencia: Guía de configuración de integración de sistemas de terceros de Kingdee Cloud Galaxy

Configuración del cliente

Todas las configuraciones de cliente siguientes usan "command": "uvx" para iniciar sin instalación; si ya tienes pip install kingdee-k3cloud-mcp, cambia "command": "uvx" por "command": "kingdee-k3cloud-mcp" y elimina el nombre del paquete de "args" (conserva el resto de parámetros, como --mode readonly). Ambos métodos son completamente equivalentes.

Claude Desktop

Edita ~/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

Crea .mcp.json en el directorio del proyecto:

{
  "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

Cursor: Settings → MCP → Add new MCP Server; Windsurf: edita ~/.codeium/windsurf/mcp_config.json. El formato de configuración de ambos es idéntico al de Claude Desktop:

{
  "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"
      }
    }
  }
}

Cline / Continue / Cherry Studio y otros clientes MCP

La estructura de configuración es exactamente la misma que la anterior: command + args + env, con los mismos uvx kingdee-k3cloud-mcp y las 5 variables de entorno. Consulta la documentación de configuración MCP de cada cliente para saber dónde rellenarlo:

Cline (extensión de VS Code): panel MCP Servers → Configure MCP Servers
Continue: campo mcpServers de ~/.continue/config.json
Cherry Studio: Configuración → Servidores MCP → Añadir servidor

Openclaw (acceso por mensajería / móvil)

Openclaw es una plataforma de agentes compatible con el mecanismo de Skills. Puedes conectar este Servidor MCP a sus canales de mensajería compatibles (como WeChat o Telegram) para «consultar inventario/documentos de Kingdee con un solo mensaje». La configuración es también una declaración estándar de Servidor MCP (command/args/env); consulta la documentación oficial de Openclaw para los pasos concretos de integración. Combinarlo con kingdee-k3cloud-skill reduce aún más los errores de campos. El alcance concreto de canales de mensajería lo determina la plataforma Openclaw.

Modo SSE (uso compartido remoto)

Si necesitas que varias personas compartan la misma instancia del servicio:

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

Dirección de conexión del cliente: http://your-server:8080/sse

Puedes habilitar la autenticación Bearer Token mediante la variable de entorno MCP_API_KEY.

Herramientas disponibles

Herramientas de consulta (disponibles en modo solo lectura)

Herramienta	Descripción
`query_bill`	Consulta datos de documentos (devuelve una matriz bidimensional)
`query_bill_json`	Consulta datos de documentos (devuelve JSON, con los nombres de campo como claves)
`count_bill`	Estima el número de filas de un resultado de consulta, para sondeos previos a consultas de gran volumen
`query_bill_all`	Consulta con paginación automática hasta completar o alcanzar el límite seguro; devuelve resultados combinados
`query_bill_to_file`	Paginación automática con escritura en streaming a un archivo local (ndjson / csv); ideal para exportar decenas de miles de filas
`query_bill_range`	Fragmentación automática por fechas (mes/semana/día) + paginación; ideal para consultas que cruzan meses/años; admite escritura a disco
`view_bill`	Consulta el detalle completo de un único registro
`query_metadata`	Consulta la estructura de campos de un formulario (metadatos)

Herramientas de escritura (disponibles en modo lectura-escritura)

Herramienta	Descripción
`save_bill`	Guardar/crear documentos
`submit_bill`	Enviar documentos
`audit_bill`	Aprobar documentos
`unaudit_bill`	Desaprobar documentos
`delete_bill`	Eliminar documentos
`execute_operation`	Ejecutar operaciones personalizadas (deshabilitar, reactivar, etc.)
`push_bill`	Empuje descendente de documentos (por ejemplo, pedido de venta → aviso de envío)

Todas las herramientas admiten cualquier formulario mediante el parámetro form_id (materiales, clientes, proveedores, pedidos de venta, pedidos de compra, etc.).

Modo solo lectura

Mediante --mode readonly o MCP_MODE=readonly se restringe el servidor para que solo exponga las 8 herramientas de consulta, evitando que la IA escriba datos por error.

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

O bien:

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

Permisos de datos

El Servidor MCP no implementa un modelo de permisos de datos por sí mismo: se conecta a Kingdee Cloud Galaxy mediante «Autorización de inicio de sesión de sistemas de terceros», con una identidad fija compuesta por KD_ACCT_ID (conjunto de cuentas) + KD_USERNAME (usuario de integración) + KD_ORG_NUM (organización, por defecto 0) de .env. Todas las llamadas a herramientas comparten esta única identidad; no se admite cambiar de usuario según quién invoque. Por lo tanto, los datos que la IA puede ver dependen por completo de los permisos configurados para este usuario de integración en Galaxy.

Configuración en el lado de Galaxy

Usa un usuario de integración dedicado (ver arriba «No se recomienda usar una cuenta de administrador») y ve a «Administración del sistema» → Gestión de usuarios → Autorización de usuarios.
Asigna permisos funcionales: formularios a los que puede acceder (por ejemplo, SAL_SaleOrder) + operaciones permitidas (consulta/creación/envío/aprobación).
Asigna permisos de datos: rango de organizaciones accesibles, reglas de datos (filtros por cliente/departamento/vendedor, etc.) y permisos de campos.
Si deseas limitar las consultas por defecto a una única organización, configura KD_ORG_NUM.

Dos compuertas adicionales en el lado MCP

Estas son complementos de los permisos y no sustituyen la configuración de permisos en Galaxy:

--mode readonly / MCP_MODE=readonly: desactivan globalmente todas las herramientas de escritura.
MCP_API_KEY: autenticación de conexión en transportes SSE / streamable-http (no aplica en modo stdio).

Diagnóstico: dos manifestaciones de problemas de permisos

Síntoma	Causa	Solución
Error 500, con el mensaje de error transmitido tal cual	Permisos funcionales insuficientes	Completa en Galaxy los permisos de formulario/operación correspondientes para el usuario de integración
La consulta no da error, pero devuelve pocas filas o ninguna	Las reglas de datos filtran silenciosamente	Inicia sesión en la interfaz web de Galaxy con la misma cuenta de usuario de integración, ejecuta la misma consulta y compara el número de filas para confirmar si hay filtrado por permisos

⚠️ El segundo caso se confunde fácilmente con «realmente no hay datos en ese período»: count_bill / query_bill* devuelven resultados ya filtrados por permisos, por lo que no es posible distinguir por sí mismos entre «no hay datos» y «los datos están bloqueados por permisos».

Depuración

Usa MCP Inspector para la depuración visual:

uvx mcp dev src/kingdee_k3cloud_mcp/server.py

Notas de arquitectura

AI 助手（Claude Desktop / Claude Code / Cursor / Cline / Openclaw 等）
        │  MCP 协议
        ▼
kingdee-k3cloud-mcp（本项目）
        │  Kingdee Web API SDK
        ▼
金蝶云星空 K3Cloud

Este proyecto utiliza el SDK oficial de Python de Kingdee (kingdee-cdp-webapi-sdk) para comunicarse con la API de K3Cloud y lo encapsula como herramientas MCP estándar mediante FastMCP.

Casos de uso adecuados

Existen varias soluciones de integración MCP para el ERP de Kingdee, cada una con sus ventajas. Este proyecto es más adecuado para los siguientes escenarios:

Agentes de IA en entornos de producción que requieren estabilidad a largo plazo: --mode readonly proporciona un límite de solo lectura; las credenciales se validan automáticamente al iniciar, y los errores de configuración se ven en el registro de arranque sin esperar a la primera llamada; los fallos de autenticación devuelven un diagnóstico claro en lugar de mensajes engañosos, y la resolución de problemas no depende de suposiciones.
Consultas/exportaciones con grandes volúmenes de datos: las tres primitivas avanzadas query_bill_all (paginación automática), query_bill_to_file (escritura en streaming a disco) y query_bill_range (fragmentación por fechas) están diseñadas para datos de decenas de miles de filas, evitando que el modelo escriba bucles de paginación manuales.
Implementaciones de Kingdee con campos personalizados / desarrollo secundario: la herramienta query_metadata permite que la IA descubra por sí misma la estructura real de campos del formulario antes de consultar, sin depender de tablas de campos predefinidas; combinado con kingdee-k3cloud-skill, también se pueden encapsular los formularios/campos/flujos de aprobación específicos de la empresa como conocimiento reutilizable.
Necesidad de coexistencia de múltiples métodos de acceso: el mismo servidor admite stdio (IDE local), SSE y streamable-http (despliegue compartido remoto), y también puede integrarse como herramienta de Openclaw en canales de mensajería.

Si tu caso es una prueba ligera personal y buscas ejecutar la primera consulta en pocos minutos, este proyecto también admite pip install para una instalación en un solo paso y uso inmediato. La elección entre una u otra opción depende de si valoras más «instalar y usar» o «funcionar de forma estable a largo plazo en producción».

¿Por qué MCP en lugar de llamadas directas?

Hacer que la IA construya solicitudes HTTP directamente mediante Skills para acceder al ERP es técnicamente viable, pero introduce una serie de riesgos de seguridad. El modelo de aislamiento de procesos de MCP resuelve estos problemas de raíz.

Las credenciales no entran en el contexto del LLM

El Servidor MCP se ejecuta como un proceso independiente; las credenciales (KD_APP_SEC, dirección del servidor, ID del conjunto de cuentas) se inyectan mediante variables de entorno, y el modelo nunca las ve. Si se usara un Skill para llamar directamente, las credenciales tendrían que aparecer en el prompt o en el contexto de la conversación; si el registro del diálogo se exporta, el contexto se captura en una captura de pantalla, o el modelo las filtra accidentalmente, el secreto queda expuesto.

Límites de permisos forzados, no dependientes de instrucciones en el prompt

Un Skill es una «recomendación»: el modelo puede malinterpretarla o ser evadido por entradas cuidadosamente construidas. El --mode readonly del Servidor MCP es una restricción física: las herramientas de escritura simplemente no existen en la lista de herramientas, por lo que el modelo no puede usarlas aunque quiera. Es la diferencia esencial entre «decirle al becario que no borre datos» y «el becario no tiene permiso de DELETE».

Aislamiento de red

El Servidor MCP se despliega en la intranet de la empresa (o en la máquina local) y puede acceder directamente al ERP interno; el LLM se ejecuta en la nube y nunca contacta directamente con la red interna. Con el transporte stdio, todo el tráfico del ERP fluye entre procesos locales, sin pasar por ninguna red externa.

Cadena de auditoría completa

Cada llamada a herramienta pasa por el Servidor MCP, donde se puede registrar de forma unificada el tipo de operación, los parámetros, la marca de tiempo y el origen de la llamada. Con la llamada directa, cada solicitud de la IA es una caja negra invisible para el equipo de seguridad de la empresa.

Principio de privilegio mínimo

El usuario de integración (KD_USERNAME) puede limitarse dentro de Kingdee a módulos específicos y permisos de solo lectura. El Servidor MCP hereda y transmite esas limitaciones; el LLM no necesita conocer los límites de permisos, estos se aplican de forma natural.

Opinión personal

Tratar al LLM como un llamador externo no confiable (en lugar de un sistema interno confiable) es el enfoque de diseño de confianza cero correcto. La capa MCP separa claramente las responsabilidades de Skill y MCP: el Skill se encarga de «cuándo y cómo usar» (política), y el MCP de «qué se puede hacer» (mecanismo). Incluso si en el futuro los modelos son más potentes o aparecen ataques de inyección de prompt, el radio de explosión en el peor caso queda delimitado por el modelo de permisos del Servidor MCP, no por la «conciencia» del modelo.

Skill complementario (para agentes compatibles con Skills)

kingdee-k3cloud-skill es un Skill complementario para agentes de IA compatibles con el mecanismo de Skills (Claude Code, openclaw, hermes, etc.) que proporciona:

Tabla de referencia rápida de IDs de formularios comunes (BD_MATERIAL, SAL_SaleOrder, etc.)
Lista de nombres de campos verificados (evita errores 500 por nombres de campo incorrectos)
Flujos de trabajo completos: informes diarios, consulta de clientes, análisis de ventas, análisis de inventario, seguimiento de pedidos, etc.

Tras la instalación, el agente puede dominar automáticamente la forma correcta de consultar el ERP de Kingdee, sin necesidad de prueba y error repetidos.

Desarrollo

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

Instala los hooks de pre-commit (opcional, para mantener coherencia con CI):

uv run pre-commit install

Contribuyentes

Hecho con contrib.rocks.

Licencia

Apache License 2.0 — consulta LICENSE.