Supports Helm v3 operations for package management in Kubernetes, enabling installation, upgrades, and uninstallation of Helm charts through natural language commands.
Provides comprehensive access to Kubernetes functionality including resource management, deployment scaling, pod operations, security configuration, diagnostics, and monitoring through natural language.
Allows installation of the MCP tool directly from PyPI, with support for version-specific installations and development versions.
Kubectl MCP Tool
A Model Context Protocol (MCP) server for Kubernetes that enables AI assistants like Claude, Cursor, and others to interact with Kubernetes clusters through natural language.
🎥 Live Demo - Watch kubectl-mcp-tool
in Action with Claude!
🎥 Live Demo - Watch kubectl-mcp-tool
in Action with Cursor!
🎥 Live Demo - Watch kubectl-mcp-tool
in Action with Windsurf!
Features
Core Kubernetes Operations
- Connect to a Kubernetes cluster
- List and manage pods, services, deployments, and nodes
- Create, delete, and describe pods and other resources
- Get pod logs and Kubernetes events
- Support for Helm v3 operations (installation, upgrades, uninstallation)
- kubectl explain and api-resources support
- Choose namespace for next commands (memory persistence)
- Port forward to pods
- Scale deployments and statefulsets
- Execute commands in containers
- Manage ConfigMaps and Secrets
- Rollback deployments to previous versions
- Ingress and NetworkPolicy management
- Context switching between clusters
Natural Language Processing
- Process natural language queries for kubectl operations
- Context-aware commands with memory of previous operations
- Human-friendly explanations of Kubernetes concepts
- Intelligent command construction from intent
- Fallback to kubectl when specialized tools aren't available
- Mock data support for offline/testing scenarios
- Namespace-aware query handling
Monitoring
- Cluster health monitoring
- Resource utilization tracking
- Pod status and health checks
- Event monitoring and alerting
- Node capacity and allocation analysis
- Historical performance tracking
- Resource usage statistics via kubectl top
- Container readiness and liveness tracking
Security
- RBAC validation and verification
- Security context auditing
- Secure connections to Kubernetes API
- Credentials management
- Network policy assessment
- Container security scanning
- Security best practices enforcement
- Role and ClusterRole management
- ServiceAccount creation and binding
- PodSecurityPolicy analysis
- RBAC permissions auditing
- Security context validation
Diagnostics
- Cluster diagnostics and troubleshooting
- Configuration validation
- Error analysis and recovery suggestions
- Connection status monitoring
- Log analysis and pattern detection
- Resource constraint identification
- Pod health check diagnostics
- Common error pattern identification
- Resource validation for misconfigurations
- Detailed liveness and readiness probe validation
Advanced Features
- Multiple transport protocols support (stdio, SSE)
- Integration with multiple AI assistants
- Extensible tool framework
- Custom resource definition support
- Cross-namespace operations
- Batch operations on multiple resources
- Intelligent resource relationship mapping
- Error explanation with recovery suggestions
- Volume management and identification
Architecture
Model Context Protocol (MCP) Integration
The Kubectl MCP Tool implements the Model Context Protocol (MCP), enabling AI assistants to interact with Kubernetes clusters through a standardized interface. The architecture consists of:
- MCP Server: A compliant server that handles requests from MCP clients (AI assistants)
- Tools Registry: Registers Kubernetes operations as MCP tools with schemas
- Transport Layer: Supports stdio, SSE, and HTTP transport methods
- Core Operations: Translates tool calls to Kubernetes API operations
- Response Formatter: Converts Kubernetes responses to MCP-compliant responses
Request Flow
Dual Mode Operation
The tool operates in two modes:
- CLI Mode: Direct command-line interface for executing Kubernetes operations
- Server Mode: Running as an MCP server to handle requests from AI assistants
Installation
For detailed installation instructions, please see the Installation Guide.
You can install kubectl-mcp-tool directly from PyPI:
For a specific version:
The package is available on PyPI: https://pypi.org/project/kubectl-mcp-tool/1.1.1/
Prerequisites
- Python 3.9+
- kubectl CLI installed and configured
- Access to a Kubernetes cluster
- pip (Python package manager)
Global Installation
Local Development Installation
Verifying Installation
After installation, verify the tool is working correctly:
Note: This tool is designed to work as an MCP server that AI assistants connect to, not as a direct kubectl replacement. The primary command available is kubectl-mcp serve
which starts the MCP server.
Usage with AI Assistants
Using the MCP Server
The MCP Server (kubectl_mcp_tool.mcp_server
) is a robust implementation built on the FastMCP SDK that provides enhanced compatibility across different AI assistants:
Note: If you encounter any errors with the MCP Server implementation, you can fall back to using the minimal wrapper by replacing
kubectl_mcp_tool.mcp_server
withkubectl_mcp_tool.minimal_wrapper
in your configuration. The minimal wrapper provides basic capabilities with simpler implementation.
- Direct Configuration
- Key Environment Variables
MCP_LOG_FILE
: Path to log file (recommended to avoid stdout pollution)MCP_DEBUG
: Set to "1" for verbose loggingMCP_TEST_MOCK_MODE
: Set to "1" to use mock data instead of real clusterKUBECONFIG
: Path to your Kubernetes config fileKUBECTL_MCP_LOG_LEVEL
: Set to "DEBUG", "INFO", "WARNING", or "ERROR"
- Testing the MCP Server
You can test if the server is working correctly with:This will attempt to connect to the server and execute a ping command.Alternatively, you can directly run the server with:
Claude Desktop
Add the following to your Claude Desktop configuration at ~/.config/claude/mcp.json
(Windows: %APPDATA%\Claude\mcp.json
):
Cursor AI
Add the following to your Cursor AI settings under MCP by adding a new global MCP server:
Save this configuration to ~/.cursor/mcp.json
for global settings.
Note: Replace
/path/to/your/.kube/config
with the actual path to your kubeconfig file. On most systems, this is~/.kube/config
.
Windsurf
Add the following to your Windsurf configuration at ~/.config/windsurf/mcp.json
(Windows: %APPDATA%\WindSurf\mcp.json
):
Automatic Configuration
For automatic configuration of all supported AI assistants, run the provided installation script:
This script will:
- Install the required dependencies
- Create configuration files for Claude, Cursor, and WindSurf
- Set up the correct paths and environment variables
- Test your Kubernetes connection
Prerequisites
- kubectl installed and in your PATH
- A valid kubeconfig file
- Access to a Kubernetes cluster
- Helm v3 (optional, for Helm operations)
Examples
List Pods
Deploy an Application
Check Pod Logs
Port Forwarding
Development
Project Structure
MCP Server Tools
The MCP Server implementation (kubectl_mcp_tool.mcp_server
) provides a comprehensive set of 26 tools that can be used by AI assistants to interact with Kubernetes clusters:
Core Kubernetes Resource Management
- get_pods - Get all pods in the specified namespace
- get_namespaces - Get all Kubernetes namespaces
- get_services - Get all services in the specified namespace
- get_nodes - Get all nodes in the cluster
- get_configmaps - Get all ConfigMaps in the specified namespace
- get_secrets - Get all Secrets in the specified namespace
- get_deployments - Get all deployments in the specified namespace
- create_deployment - Create a new deployment
- delete_resource - Delete a Kubernetes resource
- get_api_resources - List Kubernetes API resources
- kubectl_explain - Explain a Kubernetes resource using kubectl explain
Helm Operations
- install_helm_chart - Install a Helm chart
- upgrade_helm_chart - Upgrade a Helm release
- uninstall_helm_chart - Uninstall a Helm release
Security Operations
- get_rbac_roles - Get all RBAC roles in the specified namespace
- get_cluster_roles - Get all cluster-wide RBAC roles
Monitoring and Diagnostics
- get_events - Get all events in the specified namespace
- get_resource_usage - Get resource usage statistics via kubectl top
- health_check - Check cluster health by pinging the API server
- get_pod_events - Get events for a specific pod
- check_pod_health - Check the health status of a pod
- get_logs - Get logs from a pod
Cluster Management
- switch_context - Switch current kubeconfig context
- get_current_context - Get current kubeconfig context
- port_forward - Forward local port to pod port
- scale_deployment - Scale a deployment
All tools return structured data with success/error information and relevant details, making it easy for AI assistants to process and understand the responses.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A Model Context Protocol server that enables AI assistants to interact with Kubernetes clusters through natural language, supporting core Kubernetes operations, monitoring, security, and diagnostics.
- 🎥 Live Demo - Watch kubectl-mcp-tool in Action with Claude!
- 🎥 Live Demo - Watch kubectl-mcp-tool in Action with Cursor!
- 🎥 Live Demo - Watch kubectl-mcp-tool in Action with Windsurf!
- Features
- Architecture
- Installation
- Usage with AI Assistants
- Prerequisites
- Examples
- Development
- Project Structure
- MCP Server Tools
- Contributing
- License
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server that enables AI assistants to interact with Coolify instances through natural language, allowing management of servers, applications, databases, and deployments.Last updated -852TypeScript
- -securityAlicense-qualityAn MCP server that enables interaction with Kubernetes/Minikube clusters through natural language, allowing AI agents like Codename Goose to manage Kubernetes resources via the Model Context Protocol.Last updated -PythonMIT License
- -securityFlicense-qualityA gateway for Generative AI systems to interact with multiple Kubernetes clusters through Model Context Protocol, enabling comprehensive Kubernetes resource operations and multi-cluster management.Last updated -241TypeScript
Kong Konnect MCP Serverofficial
AsecurityAlicenseAqualityA Model Context Protocol server enabling AI assistants to interact with Kong Konnect's API Gateway, providing tools to query analytics data, inspect configurations, and manage control planes through natural language.Last updated -1022TypeScriptApache 2.0