K8s MCP Server

Servidor K8s MCP

Este projeto é baseado no excelente trabalho de alexei-led/k8s-mcp-server. Agradecemos sinceramente ao autor original!

O servidor K8s MCP é um serviço acessível pela rede construído com base em fastapi-mcp. Ele permite que modelos de linguagem grandes (LLMs) como Claude executem com segurança ferramentas de CLI do Kubernetes (kubectl, istioctl, helm, argocd). Ele fornece serviços por meio do protocolo padrão de controle de modelos (MCP) e suporta a passagem dinâmica de kubeconfig em cada solicitação, permitindo o gerenciamento contínuo de vários clusters Kubernetes.

Recursos principais

• Implementação padrão do MCP: Usa fastapi-mcp para expor automaticamente endpoints FastAPI como ferramentas MCP, sem implementação manual do protocolo.
• Suporte dinâmico a múltiplos clusters: Passe o conteúdo de kubeconfig codificado em Base64 diretamente em cada solicitação de API, sem necessidade de pré-configuração ou montagem de arquivos.
• Endpoints de ferramentas independentes: Cada ferramenta CLI (kubectl, helm, etc.) tem seu próprio endpoint HTTP dedicado, com estrutura clara.
• Serviço independente: Pode ser executado como um contêiner Docker autônomo ou no Kubernetes.
• Documentação OpenAPI automática: Herda os benefícios do FastAPI, gerando e fornecendo automaticamente documentação interativa da API (via /docs).

Como funciona

graph TD
    subgraph "客户端"
        A["用户 / LLM"]
    end
    
    subgraph "K8s MCP 服务器"
        B["MCP 端点 (/mcp)"]
        C["工具端点"]
        D["执行引擎"]
    end

    subgraph "目标环境"
        E["目标 Kubernetes 集群"]
    end

    A -->|"MCP 客户端连接到 /mcp"| B;
    B -->|"发现可用工具"| A;
    A -->|"发起工具调用请求"| C;
    C -->|"调用执行引擎"| D;
    D -->|"创建临时 kubeconfig 并执行命令"| E;
    E -->|"返回结果"| D;
    D -->|"返回 CommandResponse"| C;
    C -->|"将结果通过 MCP 返回"| A;

Início rápido

1. Executar o servidor K8s MCP

Inicie o servidor rapidamente localmente usando Docker:

docker run -d --rm -p 9096:9096 --name mcp-server \
  docker.io/apecloud/k8s-mcp-server:latest

O servidor agora está rodando em http://localhost:9096. Você pode acessar http://localhost:9096/docs para ver todas as ferramentas disponíveis e sua documentação de API.

2. Configurar no cliente MCP

Para qualquer cliente que suporte MCP (como mcphost, Cursor, Claude Desktop, etc.), adicione a seguinte configuração:

{
  "mcpServers": {
    "kubernetes": {
      "url": "http://localhost:9096/mcp"
    }
  }
}

Substitua localhost pelo endereço IP do host que executa k8s-mcp-server (se não estiver na mesma máquina).

3. Começar a usar

Após iniciar seu cliente MCP, ele descobrirá automaticamente as ferramentas fornecidas pelo servidor K8s MCP. Agora você pode começar a dar comandos.

• "Usando a ferramenta kubectl, execute o comando get pods -n default."
• "Ajude-me a verificar o status de nginx-deployment no namespace prod."

Desenvolvimento e execução local

1. Executar o servidor K8s MCP

Você pode iniciar o servidor rapidamente localmente usando o comando quick-start em Makefile:

make quick-start

Isso construirá a imagem Docker e executará o contêiner localmente, e o servidor estará rodando em http://localhost:9096.

2. Verificar o status do servidor

Assim que o servidor estiver iniciado, você pode verificar seu status de saúde com o seguinte comando curl:

curl http://localhost:9096/health

Se o servidor estiver funcionando corretamente, você receberá uma resposta de sucesso.

Executar a partir do código-fonte

Se você deseja executar o servidor K8s MCP a partir do código-fonte, siga estas etapas:

1. Clonar o repositório

Se você ainda não clonou o repositório deste projeto, faça isso primeiro:

git clone https://github.com/apecloud/mcp-k8s.git
cd mcp-k8s

2. Criar e ativar o ambiente virtual

Recomenda-se usar um ambiente virtual para gerenciar as dependências do projeto:

python3 -m venv .venv
source .venv/bin/activate

3. Instalar dependências

Instale todas as dependências necessárias para o projeto:

pip install .

4. Executar o servidor

Use uvicorn para iniciar o aplicativo FastAPI:

uvicorn src.k8s_mcp_server.app:app --host 0.0.0.0 --port 9096

5. Verificar o status do servidor

Após o servidor iniciar, você pode verificar seu status de saúde com o seguinte comando curl:

curl http://localhost:9096/health

Se o servidor estiver funcionando corretamente, você receberá uma resposta de sucesso.

Exemplo de uso da API (Curl)

Você pode interagir diretamente com os endpoints de ferramentas do servidor via curl.

Método de autenticação Kubeconfig

As informações de kubeconfig podem ser fornecidas de duas maneiras principais:

1. Através do cabeçalho HTTP (X-Kubeconfig):

   • Coloque o conteúdo de kubeconfig codificado em Base64 no cabeçalho X-Kubeconfig.
   • Essa abordagem pode economizar consumo de tokens para modelos de linguagem grandes, pois kubeconfig não é contado como parte do corpo da solicitação na entrada do modelo.

2. Através do corpo da solicitação (campo kubeconfig):

   • Coloque o conteúdo de kubeconfig codificado em Base64 como o valor do campo kubeconfig no corpo da solicitação JSON.

Exemplo:

1. Codifique o conteúdo de seu kubeconfig em Base64:

   # macOS
   KUBECONFIG_B64=$(cat ~/.kube/config | base64)
   
   # Linux
   KUBECONFIG_B64=$(cat ~/.kube/config | base64 -w 0)
   

2. Envie a solicitação através do cabeçalho da solicitação (X-Kubeconfig):

   curl -X POST http://localhost:9096/tools/kubectl \
     -H "Content-Type: application/json" \
     -H "X-Kubeconfig: $KUBECONFIG_B64" \
     -d @- << EOF
   {
     "command": "get pods -n default"
   }
   EOF
   

3. Envie a solicitação através do corpo da solicitação:

   curl -X POST http://localhost:9096/tools/kubectl \
     -H "Content-Type: application/json" \
     -d @- << EOF
   {
     "command": "get pods -n default",
     "kubeconfig": "$KUBECONFIG_B64"
   }
   EOF
   

   Você receberá uma resposta JSON contendo o resultado da execução do comando.

Recursos

• Várias ferramentas Kubernetes: kubectl, helm, istioctl e argocd.
• Suporte nativo a provedores de nuvem: Como kubeconfig é passado dinamicamente, qualquer cluster Kubernetes compatível com padrões é suportado nativamente, incluindo AWS EKS, Google GKE e Azure AKS.
• Segurança: Executa como usuário não root no contêiner.
• Configuração fácil: Configuração simples por meio de variáveis de ambiente.

Documentação

• Documentação da API: Após iniciar o servidor, acesse o caminho /docs para obter a documentação interativa completa da API.
• Documentação do fastapi-mcp: https://github.com/tadata-org/fastapi_mcp

Contribuição

Aceitamos contribuições da comunidade! Sinta-se à vontade para enviar problemas e solicitações de pull.