Kingdee K3Cloud ERP

Servidor MCP para Kingdee K3Cloud (金蝶云星空) — um dos sistemas ERP mais utilizados na China. Conecta assistentes de IA (Claude Desktop, Cursor, Cline, Cherry Studio, etc.) ao ERP Kingdee por meio de linguagem natural.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP da Kingdee (Kingdee K3Cloud MCP)

English | 中文

Site oficial do Kingdee MCP | GitHub | PyPI

O Kingdee MCP Server (Kingdee K3Cloud MCP) é voltado para o ERP Kingdee Cloud Galaxy, permitindo que assistentes de IA (Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, Cherry Studio e qualquer outro cliente compatível com o protocolo MCP) consultem e operem o sistema ERP Kingdee por meio de linguagem natural. É um pacote PyPI padrão; pip install ou uvx podem ser executados diretamente, sem vínculo com um gerenciador de pacotes específico.

Dica: após a integração por meio de plataformas de agente compatíveis com MCP, como Openclaw, é possível consultar estoque e documentos por linguagem natural nos canais de IM suportados (como WeChat, Telegram), sem abrir a interface web da Kingdee. Agentes de IA com mecanismo de Skill (Claude Code, Openclaw etc.) também podem usar o kingdee-k3cloud-skill para uma experiência ainda melhor — a Skill injeta no agente o conhecimento sobre campos de formulários da Kingdee, padrões de consulta comuns e fluxos de trabalho, reduzindo bastante as tentativas e erros, mas não é obrigatória; o MCP Server já funciona de forma independente com qualquer cliente MCP usando todas as ferramentas.

┌─────────────────────┐    ┌─────────────────────┐    ┌──────────────────┐
│  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.

Recursos

15 ferramentas MCP: cobrem consulta, exportação de grandes volumes de dados, inclusão, envio, aprovação, cancelamento de aprovação, exclusão, push-down e outras operações principais
Design de interface genérico: um único parâmetro form_id suporta todos os formulários — materiais, clientes, pedidos de venda, pedidos de compra etc. — sem necessidade de configuração específica por negócio
Primitivas de consulta avançadas: query_bill_all (paginação automática), query_bill_to_file (gravação em fluxo contínuo), query_bill_range (fatiamento por data), eliminando completamente a carga de loops manuais do modelo
Modo somente leitura/leitura e escrita: permite restringir a IA apenas a consultas, evitando operações acidentais
Diagnóstico de falha de autenticação: valida as credenciais na inicialização; erros de credenciais/autorização retornam instruções acionáveis de correção, em vez da mensagem enganosa da Kingdee "informações de sessão perdidas"
Múltiplos protocolos de transporte: suporte a stdio (local), SSE e streamable-http (compartilhamento remoto)
Pacote Python padrão: instale com pip install, requer apenas Python 3.10+, sem dependência obrigatória de gerenciador de pacotes
Validação de entrada com segurança de tipos: todas as entradas das ferramentas são baseadas em anotações de tipo, com validação Pydantic em tempo de execução feita pelo FastMCP na chamada; erros de estrutura de parâmetros são bloqueados antes de chegar à API da Kingdee

Início rápido em 5 minutos

Instale: pip install kingdee-k3cloud-mcp (ou use uvx kingdee-k3cloud-mcp para executar sem instalação)
No "Login de autorização de sistemas de terceiros" do Kingdee Cloud Galaxy, solicite o ID/segredo do aplicativo e obtenha as 5 variáveis de ambiente obrigatórias (veja Configuração abaixo)
Preencha as variáveis na configuração do seu cliente MCP (veja Configuração do cliente abaixo), salve e reinicie
Faça perguntas diretamente em linguagem natural, por exemplo:
- "Consulte os pedidos de venda aprovados na semana passada, ordenados por valor"
- "Qual é o estoque atual do material XX em cada armazém?"
- "Exporte todos os documentos de saída de venda de março como csv"

Início rápido

Opção 1: instalação via pip (recomendada, sem uv)

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

Pacote PyPI padrão, requer apenas Python 3.10+, sem dependência de uv. Atenção: na inicialização do serviço, as 5 variáveis de ambiente obrigatórias (KD_SERVER_URL, KD_ACCT_ID, KD_USERNAME, KD_APP_ID, KD_APP_SEC) devem ser fornecidas; caso contrário, ocorrerá erro e o serviço será encerrado.

Uso no cliente MCP (recomendado, veja a seção "Configuração do cliente" abaixo): informe por meio do campo env na configuração do cliente.

Para testes manuais, você pode fornecer as variáveis de ambiente de qualquer uma das seguintes 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

Opção 2: execução direta com uvx (sem instalação)

Sem necessidade de pip install; o uvx cria automaticamente um ambiente isolado e executa. O uso é idêntico ao acima; basta substituir kingdee-k3cloud-mcp por uvx kingdee-k3cloud-mcp:

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

Opção 3: execução a partir do código-fonte

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

Configuração

Copie o modelo de variáveis de ambiente e preencha:

cp .env.example .env

Variável de ambiente	Descrição	Exemplo
`KD_SERVER_URL`	Endereço do servidor Kingdee (deve terminar com `/k3cloud/`)	`https://your-server/k3cloud/`
`KD_ACCT_ID`	ID do conjunto de contas	`your_acct_id`
`KD_USERNAME`	Conta de usuário de integração	`your_username`
`KD_APP_ID`	ID do aplicativo	`your_app_id`
`KD_APP_SEC`	Segredo do aplicativo	`your_app_secret`
`KD_LCID`	Idioma (padrão 2052, chinês)	`2052`
`KD_ORG_NUM`	Código da organização (opcional)
`KD_STARTUP_CHECK`	Validar credenciais na inicialização (padrão ativado; `0` desativa)	`1`
`KD_STARTUP_CHECK_TIMEOUT`	Tempo limite em segundos para a verificação automática na inicialização (padrão 5)	`5`

O ID e o segredo do aplicativo de terceiros devem ser solicitados em "Login de autorização de sistemas de terceiros" no console administrativo do Kingdee Cloud Galaxy.

Explicação da configuração das variáveis de ambiente

Para configurar a integração de sistemas de terceiros no produto Kingdee Cloud Galaxy, siga as etapas abaixo para obter as 5 variáveis de ambiente:

1. Acesse o painel administrativo do Kingdee Cloud Galaxy

Faça login no sistema Kingdee Cloud Galaxy com uma conta de administrador e acesse "Login de autorização de sistemas de terceiros" no menu "Gerenciamento do sistema".
Clique no botão "Novo" para entrar na página de função de novo login de autorização de sistemas de terceiros.
Clique no botão "Obter ID do aplicativo" e, conforme as instruções, vá para a página de login de autorização de sistemas de terceiros do site Open e clique em "Nova autorização".
O usuário do site Open preenche o formulário com suas próprias informações.
Após o envio bem-sucedido, as informações do aplicativo são geradas. Copie-as e preencha no campo "Informações do aplicativo" em Kingdee Cloud Galaxy — Login de autorização de sistemas de terceiros — Obter ID do aplicativo, e clique no botão "Confirmar".
Configure o usuário de integração.
Clique no botão "Salvar"; após salvar com sucesso, clique em "Gerar link de teste" para verificar se o link funciona.

Atenção: o ID do centro de banco de dados atual (ou seja, o ID do conjunto de contas) pode ser obtido nas informações exibidas ao gerar o link de teste.

2. Obter KD_SERVER_URL

Endereço do servidor Kingdee, no formato https://your-server/k3cloud/, onde:

your-server é o domínio ou endereço IP do servidor Kingdee Cloud Galaxy
Geralmente termina com /k3cloud/
Exemplo: https://erp.company.com/k3cloud/

3. Obter KD_ACCT_ID — ID do conjunto de contas

4. Obter KD_USERNAME — conta do usuário de integração

Use uma conta com permissões de operação nos módulos relevantes. Não é recomendado usar a conta de administrador. Sugere-se criar uma conta de usuário de integração dedicada e atribuir a ela as permissões de operação necessárias nos módulos.

5. Obter KD_APP_ID — ID do aplicativo e KD_APP_SEC — segredo do aplicativo

Atenção: para visualizar o APP_SECRET, você pode consultá-lo a qualquer momento nos detalhes do aplicativo; se perdê-lo, também é possível regenerá-lo pelo recurso "Redefinir".

6. Validar a configuração

Após a configuração, você pode validar a conexão com o seguinte comando:

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

Se vir "MCP Server running" ou saída semelhante, a configuração foi bem-sucedida.

Documento de referência: Guia de configuração de integração de sistemas de terceiros do Kingdee Cloud Galaxy

Configuração do cliente

Todas as configurações de cliente abaixo usam "command": "uvx" para iniciar sem instalação; se você já tiver pip install kingdee-k3cloud-mcp, basta substituir "command": "uvx" por "command": "kingdee-k3cloud-mcp" e remover o nome do pacote de "args" (mantendo os demais parâmetros, como --mode readonly). Os dois modos têm exatamente o mesmo efeito.

Claude Desktop

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

Crie .mcp.json no diretório do projeto:

{
  "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: edite ~/.codeium/windsurf/mcp_config.json. O formato de configuração dos dois é igual ao do 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 e outros clientes MCP

A estrutura de configuração é exatamente a mesma acima — command + args + env, preenchendo o mesmo uvx kingdee-k3cloud-mcp e as 5 variáveis de ambiente. Consulte a documentação de configuração MCP de cada cliente para saber onde preencher:

Cline (plugin VS Code): painel MCP Servers → Configure MCP Servers
Continue: campo mcpServers de ~/.continue/config.json
Cherry Studio: Configurações → Servidores MCP → Adicionar servidor

Openclaw (acesso via IM / dispositivos móveis)

Openclaw é uma plataforma de agentes com mecanismo de Skill que pode conectar este MCP Server aos canais de IM suportados (como WeChat, Telegram), permitindo "enviar uma mensagem para consultar estoque/documentos da Kingdee". A configuração também é uma declaração padrão de MCP Server (command/args/env); para os passos específicos de integração, consulte a documentação oficial do Openclaw. O uso conjunto com o kingdee-k3cloud-skill pode reduzir ainda mais as tentativas de campos. O suporte específico a canais de IM é determinado pela plataforma Openclaw.

Modo SSE (compartilhamento remoto)

Se várias pessoas precisarem compartilhar a mesma instância do serviço:

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

Endereço de conexão do cliente: http://your-server:8080/sse

A autenticação por Bearer Token pode ser habilitada pela variável de ambiente MCP_API_KEY.

Ferramentas disponíveis

Ferramentas de consulta (disponíveis no modo somente leitura)

Ferramenta	Descrição
`query_bill`	Consulta dados de documentos (retorna matriz bidimensional)
`query_bill_json`	Consulta dados de documentos (retorna JSON, com nomes de campos como chaves)
`count_bill`	Estima o número de linhas do resultado da consulta, para sondagem antes de consultas de grande volume
`query_bill_all`	Consulta com paginação automática até concluir ou atingir o limite seguro, retornando resultado mesclado
`query_bill_to_file`	Paginação automática com gravação em fluxo contínuo em arquivo local (ndjson / csv), ideal para exportação de dezenas de milhares de linhas
`query_bill_range`	Fatiamento automático por data (mês/semana/dia) + paginação, ideal para consultas entre meses/anos, com suporte a gravação em disco
`view_bill`	Exibe os detalhes completos de um único registro
`query_metadata`	Consulta a estrutura de campos do formulário (metadados)

Ferramentas de escrita (disponíveis no modo leitura e escrita)

Ferramenta	Descrição
`save_bill`	Salva/inclui documentos
`submit_bill`	Envia documentos
`audit_bill`	Aprova documentos
`unaudit_bill`	Cancela aprovação de documentos
`delete_bill`	Exclui documentos
`execute_operation`	Executa operações personalizadas (desativar, reativar etc.)
`push_bill`	Push-down de documentos (ex.: pedido de venda → aviso de remessa)

Todas as ferramentas suportam qualquer formulário (materiais, clientes, fornecedores, pedidos de venda, pedidos de compra etc.) por meio do parâmetro form_id.

Modo somente leitura

Use --mode readonly ou MCP_MODE=readonly para restringir o servidor a expor apenas as 8 ferramentas de consulta, evitando que a IA escreva dados por engano.

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

Ou:

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

Permissões de dados

O MCP Server não implementa um modelo de permissões de dados — ele se conecta ao Kingdee Cloud Galaxy por meio de "Login de autorização de sistemas de terceiros", com identidade fixa de .env (conjunto de contas) + KD_ACCT_ID (usuário de integração) + KD_USERNAME (organização, padrão KD_ORG_NUM) em 0. Todas as chamadas de ferramentas compartilham essa única identidade; não há suporte a troca de usuário por chamador. Portanto, o que a IA consegue ver é totalmente determinado pelas permissões desse usuário de integração no Galaxy.

Configuração no lado do Galaxy

Use um usuário de integração dedicado (veja acima "não é recomendado usar a conta de administrador") e acesse "Gerenciamento do sistema" → Gerenciamento de usuários → Autorização de usuários
Atribua permissões de função: formulários permitidos (ex.: SAL_SaleOrder) + operações permitidas (consulta/inclusão/envio/aprovação)
Atribua permissões de dados: escopo de organizações acessíveis, regras de dados (filtros por cliente/departamento/vendedor etc.), permissões de campos
Se desejar limitar a consulta por padrão a uma única organização, defina KD_ORG_NUM

Duas barreiras adicionais no lado do MCP

Estas são complementos às permissões e não substituem a configuração de permissões no lado do Galaxy:

--mode readonly / MCP_MODE=readonly: desativa globalmente todas as ferramentas de escrita
MCP_API_KEY: autenticação de conexão nos transportes SSE / streamable-http (não se aplica ao modo stdio)

Diagnóstico: duas manifestações de problemas de permissão

Sintoma	Causa	Tratamento
Erro 500, mensagem de erro repassada como está	Permissão de função insuficiente	No Galaxy, complemente as permissões de formulário/operação do usuário de integração
Consulta sem erro, mas com poucas ou nenhuma linha	Regra de dados com filtro silencioso	Faça login na interface web do Galaxy com a mesma conta do usuário de integração, execute a mesma condição de consulta e compare o número de linhas para confirmar se houve filtro por permissão

⚠️ O segundo caso pode ser facilmente confundido com "realmente não há dados nesse período" — count_bill / query_bill* retornam resultados já filtrados por permissão e, por si só, não conseguem distinguir "não há dados" de "dados bloqueados por permissão".

Depuração

Use o MCP Inspector para depuração visual:

uvx mcp dev src/kingdee_k3cloud_mcp/server.py

Explicação da arquitetura

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

Este projeto usa o SDK Python oficial da Kingdee (kingdee-cdp-webapi-sdk) para comunicação com a API K3Cloud e o FastMCP para encapsulá-lo como ferramentas MCP padrão.

Cenários de uso

Há mais de uma forma de integrar o ERP Kingdee via MCP, cada uma com seu foco. Este projeto é mais adequado aos seguintes cenários:

Agentes de IA em produção que precisam de estabilidade a longo prazo: --mode readonly fornece limite somente leitura; as credenciais são validadas automaticamente na inicialização, e erros de configuração aparecem no log de inicialização, sem esperar a primeira chamada de ferramenta; falhas de autenticação retornam diagnóstico claro em vez de mensagens enganosas, eliminando adivinhação
Consultas/exportações com grandes volumes de dados: as três primitivas avançadas query_bill_all (paginação automática), query_bill_to_file (gravação em fluxo contínuo) e query_bill_range (fatiamento por data) são feitas para dados na casa de dezenas de milhares de linhas, evitando que o modelo escreva loops de paginação manualmente
Implantações Kingdee com campos personalizados / desenvolvimento secundário: a ferramenta query_metadata permite que a IA descubra sozinha a estrutura real de campos do formulário antes da consulta, sem depender de tabelas de campos predefinidas; com o kingdee-k3cloud-skill, também é possível encapsular formulários/campos/fluxos de aprovação exclusivos da empresa como conhecimento reutilizável
Necessidade de múltiplas formas de acesso coexistindo: o mesmo servidor suporta stdio (IDE local), SSE e streamable-http (implantação compartilhada remota), além de poder ser usado como ferramenta do Openclaw para acesso via canais de IM

Se o seu cenário é uso pessoal leve, buscando a primeira consulta funcionando em poucos minutos, este projeto também suporta instalação em um passo com pip install, pronta para uso; a escolha entre as opções depende do que você valoriza mais: "instalar e usar" ou "rodar de forma estável em produção a longo prazo".

Por que MCP em vez de chamada direta?

Fazer a IA construir requisições HTTP diretamente via Skill para acessar o ERP é tecnicamente viável, mas introduz uma série de riscos de segurança. O modelo de isolamento de processos do MCP resolve esses problemas na raiz.

Credenciais não entram no contexto do LLM

O MCP Server roda como um processo independente; as credenciais (KD_APP_SEC, endereço do servidor, ID do conjunto de contas) são injetadas por variáveis de ambiente, e o modelo nunca vê essas informações. Se a chamada fosse feita diretamente via Skill, as credenciais precisariam aparecer no prompt ou no contexto da conversa; uma vez que o log da conversa fosse exportado, o contexto capturado em tela ou o modelo as exibisse acidentalmente, o segredo estaria vazado.

Limite de permissão forçado, em vez de depender de instruções no prompt

Skill é uma "recomendação" — o modelo pode interpretar errado ou ser contornado por entradas cuidadosamente construídas. O --mode readonly do MCP Server é uma limitação física: as ferramentas de escrita simplesmente não existem na lista de ferramentas; o modelo não consegue usá-las mesmo que queira. Essa é a diferença essencial entre "dizer ao estagiário para não apagar dados" e "o estagiário simplesmente não tem permissão de DELETE".

Isolamento de rede

O MCP Server é implantado na intranet da empresa (ou na máquina local) e pode acessar diretamente o ERP interno; o LLM roda na nuvem e nunca toca diretamente a rede interna. Com transporte stdio, todo o tráfego do ERP flui entre processos locais, sem passar por nenhuma rede externa.

Trilha de auditoria completa

Cada chamada de ferramenta passa pelo MCP Server, que pode registrar de forma unificada o tipo de operação, parâmetros, timestamp e origem da chamada. Na chamada direta, cada requisição da IA é uma caixa-preta invisível para a equipe de segurança da empresa.

Princípio do menor privilégio

O usuário de integração (KD_USERNAME) pode ser restrito no sistema Kingdee a módulos específicos e permissão somente leitura. O MCP Server herda e repassa essas restrições; o LLM não precisa conhecer os limites de permissão — eles valem naturalmente.

Opinião pessoal

Tratar o LLM como chamador externo não confiável (em vez de sistema interno confiável) é a abordagem correta de design de confiança zero. A camada MCP separa claramente as responsabilidades de Skill e MCP: a Skill cuida de "quando usar e como usar" (estratégia), e o MCP cuida de "o que pode fazer" (mecanismo). Mesmo que no futuro os modelos fiquem mais capazes, ou ocorram ataques de injeção de prompt, o raio de explosão no pior caso é limitado pelo modelo de permissões do MCP Server, e não pela "consciência" do modelo.

Skill complementar (para agentes com suporte a Skill)

O kingdee-k3cloud-skill é uma Skill complementar para agentes de IA com mecanismo de Skill (Claude Code, openclaw, hermes etc.), que oferece:

Tabela de consulta rápida de IDs de formulários comuns (BD_MATERIAL, SAL_SaleOrder etc.)
Lista de nomes de campos validados (evita erro 500 por nome de campo incorreto)
Fluxos de trabalho completos: relatórios diários, consulta de clientes, análise de vendas, análise de estoque, rastreamento de pedidos etc.

Após a instalação, o agente aprende automaticamente a forma correta de consultar o ERP Kingdee, sem tentativa e erro repetidos.

Desenvolvimento

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

Instale os pre-commit hooks (opcional, para manter consistência com o CI):

uv run pre-commit install

Contribuidores

Feito com contrib.rocks.

Licença

Apache License 2.0 — consulte LICENSE