Herramienta MCP de Kubectl
Un servidor de Protocolo de contexto de modelo (MCP) para Kubernetes que permite que los asistentes de IA como Claude, Cursor y otros interactúen con los clústeres de Kubernetes a través del lenguaje natural.
Características
Operaciones principales de Kubernetes
- [x] Conectarse a un clúster de Kubernetes
- [x] Enumerar y administrar pods, servicios, implementaciones y nodos
- [x] Crear, eliminar y describir pods y otros recursos
- [x] Obtener registros de pods y eventos de Kubernetes
- [x] Soporte para operaciones de Helm v3 (instalación, actualizaciones, desinstalación)
- [x] Explicación de kubectl y soporte de api-resources
- [x] Elija el espacio de nombres para los próximos comandos (persistencia de memoria)
- [x] Reenvío de puertos a pods
- [x] Implementaciones a escala y conjuntos con estado
- [x] Ejecutar comandos en contenedores
- [x] Administrar ConfigMaps y secretos
- [x] Revertir implementaciones a versiones anteriores
- [x] Gestión de políticas de entrada y red
- [x] Cambio de contexto entre clústeres
Procesamiento del lenguaje natural
- [x] Procesar consultas en lenguaje natural para operaciones de kubectl
- [x] Comandos conscientes del contexto con memoria de operaciones anteriores
- [x] Explicaciones intuitivas de los conceptos de Kubernetes
- [x] Construcción de comandos inteligentes a partir de la intención
- [x] Recurrir a kubectl cuando no se disponga de herramientas especializadas
- [x] Soporte de datos simulados para escenarios de prueba/fuera de línea
- [x] Manejo de consultas teniendo en cuenta el espacio de nombres
Escucha
- [x] Supervisión del estado del clúster
- [x] Seguimiento de la utilización de recursos
- [x] Estado del pod y controles de salud
- [x] Monitoreo y alerta de eventos
- [x] Análisis de capacidad y asignación de nodos
- [x] Seguimiento del rendimiento histórico
- [x] Estadísticas de uso de recursos a través de kubectl top
- [x] Seguimiento de la preparación y actividad de los contenedores
Seguridad
- [x] Validación y verificación de RBAC
- [x] Auditoría del contexto de seguridad
- [x] Conexiones seguras a la API de Kubernetes
- [x] Gestión de credenciales
- [x] Evaluación de políticas de red
- [x] Escaneo de seguridad de contenedores
- [x] Aplicación de las mejores prácticas de seguridad
- [x] Gestión de roles y roles de clúster
- [x] Creación y vinculación de ServiceAccount
- [x] Análisis de PodSecurityPolicy
- [x] Auditoría de permisos RBAC
- [x] Validación del contexto de seguridad
Diagnóstico
- [x] Diagnóstico y resolución de problemas del clúster
- [x] Validación de configuración
- [x] Análisis de errores y sugerencias de recuperación
- [x] Supervisión del estado de la conexión
- [x] Análisis de registros y detección de patrones
- [x] Identificación de restricciones de recursos
- [x] Diagnóstico de verificación del estado del pod
- [x] Identificación de patrones de error comunes
- [x] Validación de recursos para configuraciones incorrectas
- [x] Validación detallada de la sonda de actividad y preparación
Funciones avanzadas
- [x] Compatibilidad con múltiples protocolos de transporte (stdio, SSE)
- [x] Integración con múltiples asistentes de IA
- [x] Marco de herramientas extensible
- [x] Soporte para definición de recursos personalizados
- [x] Operaciones entre espacios de nombres
- [x] Operaciones por lotes en múltiples recursos
- [x] Mapeo inteligente de relaciones de recursos
- [x] Explicación del error con sugerencias de recuperación
- [x] Gestión e identificación de volúmenes
Arquitectura
Integración del Protocolo de Contexto de Modelo (MCP)
La herramienta MCP de Kubectl implementa el Protocolo de Contexto de Modelo (MCP) , lo que permite a los asistentes de IA interactuar con clústeres de Kubernetes mediante una interfaz estandarizada. La arquitectura consta de:
- Servidor MCP : un servidor compatible que gestiona solicitudes de clientes MCP (asistentes de IA)
- Registro de herramientas : registra las operaciones de Kubernetes como herramientas MCP con esquemas
- Capa de transporte : admite los métodos de transporte stdio, SSE y HTTP
- Operaciones principales : traduce las llamadas de herramientas a operaciones de API de Kubernetes
- Formateador de respuestas : convierte las respuestas de Kubernetes en respuestas compatibles con MCP
Flujo de solicitud
Operación en modo dual
La herramienta funciona en dos modos:
- Modo CLI : interfaz de línea de comandos directa para ejecutar operaciones de Kubernetes
- Modo servidor : se ejecuta como un servidor MCP para gestionar solicitudes de asistentes de IA
Instalación
Para obtener instrucciones de instalación detalladas, consulte la Guía de instalación .
Puede instalar kubectl-mcp-tool directamente desde PyPI:
pip install kubectl-mcp-tool
Para una versión específica:
pip install kubectl-mcp-tool==1.1.1
El paquete está disponible en PyPI: https://pypi.org/project/kubectl-mcp-tool/1.1.1/
Prerrequisitos
- Python 3.9+
- CLI de kubectl instalado y configurado
- Acceso a un clúster de Kubernetes
- pip (administrador de paquetes de Python)
Instalación global
# Install latest version from PyPI
pip install kubectl-mcp-tool
# Or install development version from GitHub
pip install git+https://github.com/rohitg00/kubectl-mcp-server.git
Instalación de Desarrollo Local
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server
# Install in development mode
pip install -e .
Verificación de la instalación
Después de la instalación, verifique que la herramienta funcione correctamente:
# Check CLI mode
kubectl-mcp --help
Nota: Esta herramienta está diseñada para funcionar como un servidor MCP al que se conectan los asistentes de IA, no como un reemplazo directo de kubectl. El comando principal disponible es kubectl-mcp serve , que inicia el servidor MCP.
Uso con asistentes de IA
Uso del servidor MCP
El servidor MCP ( kubectl_mcp_tool.mcp_server ) es una implementación sólida creada en el SDK FastMCP que proporciona compatibilidad mejorada entre diferentes asistentes de IA:
Nota : Si encuentra algún error con la implementación del servidor MCP, puede volver a usar el contenedor mínimo reemplazando kubectl_mcp_tool.mcp_server por kubectl_mcp_tool.minimal_wrapper en su configuración. El contenedor mínimo proporciona funciones básicas con una implementación más sencilla.
- Configuración directa
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config",
"PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
"MCP_LOG_FILE": "/path/to/logs/debug.log",
"MCP_DEBUG": "1"
}
}
}
}
- Variables ambientales clave
MCP_LOG_FILE : Ruta al archivo de registro (recomendado para evitar la contaminación de la salida estándar)MCP_DEBUG : Establézcalo en "1" para un registro detalladoMCP_TEST_MOCK_MODE : Establézcalo en "1" para usar datos simulados en lugar del clúster realKUBECONFIG : Ruta a su archivo de configuración de KubernetesKUBECTL_MCP_LOG_LEVEL : Establézcalo en "DEBUG", "INFO", "WARNING" o "ERROR"
- Prueba del servidor MCP Puedes probar si el servidor funciona correctamente con:
python -m kubectl_mcp_tool.simple_ping
python -m kubectl_mcp_tool
Escritorio de Claude
Agregue lo siguiente a su configuración de Claude Desktop en ~/.config/claude/mcp.json (Windows: %APPDATA%\Claude\mcp.json ):
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config"
}
}
}
}
Cursor AI
Agregue lo siguiente a la configuración de Cursor AI en MCP agregando un nuevo servidor MCP global:
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config",
"PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin"
}
}
}
}
Guarde esta configuración en ~/.cursor/mcp.json para configuraciones globales.
Nota : Reemplace /path/to/your/.kube/config con la ruta real de su archivo kubeconfig. En la mayoría de los sistemas, es ~/.kube/config .
Windsurf
Agregue lo siguiente a su configuración de Windsurf en ~/.config/windsurf/mcp.json (Windows: %APPDATA%\WindSurf\mcp.json ):
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config"
}
}
}
}
Configuración automática
Para la configuración automática de todos los asistentes de IA compatibles, ejecute el script de instalación proporcionado:
Este script hará lo siguiente:
- Instalar las dependencias necesarias
- Crear archivos de configuración para Claude, Cursor y WindSurf
- Configurar las rutas y variables de entorno correctas
- Pruebe su conexión de Kubernetes
Prerrequisitos
- kubectl instalado y en su PATH
- Un archivo kubeconfig válido
- Acceso a un clúster de Kubernetes
- Helm v3 (opcional, para operaciones de Helm)
Ejemplos
Pods de lista
List all pods in the default namespace
Implementar una aplicación
Create a deployment named nginx-test with 3 replicas using the nginx:latest image
Comprobar registros de pods
Get logs from the nginx-test pod
Reenvío de puertos
Forward local port 8080 to port 80 on the nginx-test pod
Desarrollo
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server
# Install dependencies
pip install -r requirements.txt
# Install in development mode
pip install -e .
# Run the MCP server
python -m kubectl_mcp_tool
# Run tests
python -m python_tests.run_mcp_tests
Estructura del proyecto
├── kubectl_mcp_tool/ # Main package
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Package entry point
│ ├── cli.py # CLI entry point
│ ├── mcp_server.py # MCP server implementation
│ ├── mcp_kubectl_tool.py # Main kubectl MCP tool implementation
│ ├── natural_language.py # Natural language processing
│ ├── diagnostics.py # Diagnostics functionality
│ ├── core/ # Core functionality
│ ├── security/ # Security operations
│ ├── monitoring/ # Monitoring functionality
│ ├── utils/ # Utility functions
│ └── cli/ # CLI functionality components
├── python_tests/ # Test suite
│ ├── run_mcp_tests.py # Test runner script
│ ├── mcp_client_simulator.py # MCP client simulator for mock testing
│ ├── test_utils.py # Test utilities
│ ├── test_mcp_core.py # Core MCP tests
│ ├── test_mcp_security.py # Security tests
│ ├── test_mcp_monitoring.py # Monitoring tests
│ ├── test_mcp_nlp.py # Natural language tests
│ ├── test_mcp_diagnostics.py # Diagnostics tests
│ └── mcp_test_strategy.md # Test strategy documentation
├── docs/ # Documentation
│ ├── README.md # Documentation overview
│ ├── INSTALLATION.md # Installation guide
│ ├── integration_guide.md # Integration guide
│ ├── cursor/ # Cursor integration docs
│ ├── windsurf/ # Windsurf integration docs
│ └── claude/ # Claude integration docs
├── compatible_servers/ # Compatible MCP server implementations
│ ├── cursor/ # Cursor-compatible servers
│ ├── windsurf/ # Windsurf-compatible servers
│ ├── minimal/ # Minimal server implementations
│ └── generic/ # Generic MCP servers
├── requirements.txt # Python dependencies
├── setup.py # Package setup script
├── pyproject.toml # Project configuration
├── MANIFEST.in # Package manifest
├── mcp_config.json # Sample MCP configuration
├── run_server.py # Server runner script
├── LICENSE # MIT License
├── CHANGELOG.md # Version history
├── .gitignore # Git ignore file
├── install.sh # Installation script
├── publish.sh # PyPI publishing script
└── start_mcp_server.sh # Server startup script
Herramientas del servidor MCP
La implementación del servidor MCP ( kubectl_mcp_tool.mcp_server ) proporciona un conjunto completo de 26 herramientas que los asistentes de IA pueden usar para interactuar con los clústeres de Kubernetes:
Gestión de recursos básicos de Kubernetes
- get_pods - Obtener todos los pods en el espacio de nombres especificado
- get_namespaces : obtiene todos los espacios de nombres de Kubernetes
- get_services - Obtener todos los servicios en el espacio de nombres especificado
- get_nodes - Obtener todos los nodos del clúster
- get_configmaps : obtiene todos los ConfigMaps en el espacio de nombres especificado
- get_secrets - Obtener todos los secretos en el espacio de nombres especificado
- get_deployments : obtiene todas las implementaciones en el espacio de nombres especificado
- create_deployment - Crea una nueva implementación
- delete_resource : eliminar un recurso de Kubernetes
- get_api_resources : enumera los recursos de la API de Kubernetes
- kubectl_explain : explica un recurso de Kubernetes usando kubectl explain
Operaciones de Helm
- install_helm_chart - Instalar un gráfico de Helm
- upgrade_helm_chart - Actualizar una versión de Helm
- uninstall_helm_chart - Desinstalar una versión de Helm
Operaciones de seguridad
- get_rbac_roles : obtiene todos los roles RBAC en el espacio de nombres especificado
- get_cluster_roles : obtener todos los roles RBAC de todo el clúster
Monitoreo y diagnóstico
- get_events - Obtener todos los eventos en el espacio de nombres especificado
- get_resource_usage : obtener estadísticas de uso de recursos a través de kubectl top
- health_check : verifica el estado del clúster haciendo ping al servidor API
- get_pod_events - Obtener eventos para un pod específico
- check_pod_health - Verifica el estado de salud de un pod
- get_logs - Obtener registros de un pod
Gestión de clústeres
- switch_context - Cambia el contexto actual de kubeconfig
- get_current_context - Obtener el contexto actual de kubeconfig
- port_forward - Reenvía el puerto local al puerto del pod
- scale_deployment - Escalar una implementación
Todas las herramientas devuelven datos estructurados con información de éxito/error y detalles relevantes, lo que facilita que los asistentes de IA procesen y comprendan las respuestas.
Contribuyendo
¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.
- Bifurcar el repositorio
- Crea tu rama de funciones (
git checkout -b feature/amazing-feature ) - Confirme sus cambios (
git commit -m 'Add some amazing feature' ) - Empujar a la rama (
git push origin feature/amazing-feature ) - Abrir una solicitud de extracción
Licencia
Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.