Servidor MCP para Operaciones de K8s

Servicio MCP de operaciones de Kubernetes basado en FastMCP. Encapsula acciones de diagnóstico diario como kubectl get / describe / logs / events --watch en herramientas de solo lectura invocables por LLM, permitiendo que clientes como Claude lean directamente el estado del clúster y localicen fallos en el primer punto de incidencia.

⚠️ Este proyecto solo expone herramientas de solo lectura (sin create/update/delete). No obstante, se recomienda usar un ServiceAccount de solo lectura con RBAC, como se indica en «Recomendaciones de seguridad».

Lista de herramientas

Además, se incluyen dos capacidades adicionales: @mcp.prompt (guía para diagnóstico de nodos / inspección del clúster) y @mcp.resource (resumen del clúster k8s://cluster/summary).

Related MCP server: k8s-readonly-mcp

Estructura de directorios

├── app.py              # FastMCP 实例（叶子模块，破循环导入）
├── k8s_server.py       # 入口：导入 Tools 即自动注册全部工具
├── k8s_client.py       # K8s 客户端懒加载 + 单一配置真源
├── config.py           # 12-Factor 环境变量配置
├── prompts.py          # @mcp.prompt 引导
├── resources.py        # @mcp.resource 资源
├── Tools/              # 每个工具一个文件，导入即注册
├── utils/              # 纯解析/辅助模块（无 K8s/MCP 依赖）
└── tests/              # 单元测试

Instalación y ejecución

# 1. 创建虚拟环境并安装依赖
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

# 2. 运行（HTTP transport，默认 127.0.0.1:8081）
python k8s_server.py

Ejecución de pruebas

pip install -r requirements-dev.txt
python -m pytest -q

Configuración

Toda la configuración se realiza mediante variables de entorno, con valores predeterminados (ver config.py):

Prioridad de carga de la conexión a K8s: in-cluster (dentro del Pod) → KUBECONFIG_PATH explícito → cadena oficial de resolución del kubeconfig, con una única fuente de verdad, sin ensamblar desde múltiples archivos.

Integración con clientes MCP

Tomando Claude Code como ejemplo (con transporte HTTP ya en ejecución en 127.0.0.1:8081):

{
  "mcpServers": {
    "k8s-node-server": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

Recomendaciones de seguridad

1. Usar RBAC de solo lectura: configurar un ClusterRole de solo lectura para el Pod / usuario que ejecuta este servicio, evitando usar credenciales con privilegios elevados.

2. Vincular solo a la máquina local por defecto: MCP_HOST tiene como valor predeterminado 127.0.0.1. Si se necesita exponer el servicio, asegurarse de añadir autenticación en la capa de proxy inverso (TLS + Token / OIDC), ya que el transporte HTTP en sí no tiene autenticación ni limitación de tasa.

3. No desactivar la verificación de certificados: K8S_VERIFY_SSL=false se usa únicamente para depurar temporalmente certificados autofirmados; en producción mantener true.

4. No almacenar credenciales en el repositorio: el kubeconfig contiene secretos; .gitignore ya excluye kubeconfig*, no forzar su inclusión.

Limitaciones conocidas

• Todas las herramientas son de solo lectura, sin operaciones de modificación (es una decisión de diseño deliberada).

• La serie watch_* está sujeta a un bloqueo global de concurrencia: solo se permite un watch a la vez, para evitar presión sobre el API Server.

• La salida de eventos/logs tiene un límite de longitud; los contenidos demasiado grandes se truncarán (ver la lógica de truncamiento en read_pod_log y max_count en query_events).