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
{ "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" } } } }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:
python -m kubectl_mcp_tool.simple_pingThis will attempt to connect to the server and execute a ping command.
Alternatively, you can directly run the server with:
python -m kubectl_mcp_tool
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-qualityAn MCP server that enables Claude to generate and execute AWS CLI commands, allowing users to manage AWS resources through natural language conversations.Last updated -2
- -securityFlicense-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -331
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 -1035Apache 2.0- -securityFlicense-qualityA Model Control Protocol server that extends AI assistants with Kubernetes operations capabilities, allowing for managing deployments, pods, services and other K8s resources.Last updated -2