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.
🚨 Important Notice
We are currently experiencing JSON parsing issues on our server. This has led to difficulties running MCP in:
I am actively working on resolving these issues. Given I'm handling the troubleshooting process independently, resolution may take some time as I'm conducting detailed tests for each service individually. If you can debug those issues, feel free to submit a Pull Request.
Your patience and continued support during this period are greatly appreciated. 🙏
Thank you for understanding!
Features
Core Kubernetes Operations
Natural Language Processing
Monitoring
Security
Diagnostics
Advanced Features
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:
pip install kubectl-mcp-tool
For a specific version:
pip install kubectl-mcp-tool==1.1.0
The package is available on PyPI: https://pypi.org/project/kubectl-mcp-tool/1.1.0/
Prerequisites
- Python 3.9+
- kubectl CLI installed and configured
- Access to a Kubernetes cluster
- pip (Python package manager)
Global Installation
# 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
Local Development Installation
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server
# Install in development mode
pip install -e .
Verifying Installation
After installation, verify the tool is working correctly:
# Check CLI mode
kubectl-mcp --help
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
Claude Desktop
Add the following to your Claude Desktop configuration at ~/.config/claude/mcp.json (Windows: %APPDATA%\Claude\mcp.json):
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.minimal_wrapper"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config"
}
}
}
}
Cursor AI
Add the following to your Cursor AI settings under MCP by adding a new global MCP server:
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.minimal_wrapper"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config",
"PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin"
}
}
}
}
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):
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.minimal_wrapper"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config"
}
}
}
}
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
List all pods in the default namespace
Deploy an Application
Create a deployment named nginx-test with 3 replicas using the nginx:latest image
Check Pod Logs
Get logs from the nginx-test pod
Port Forwarding
Forward local port 8080 to port 80 on the nginx-test pod
Development
# 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 tests
python -m python_tests.test_all_features
Project Structure
├── kubectl_mcp_tool/ # Main package
│ ├── __init__.py # Package initialization
│ ├── 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
├── 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
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.