Kubectl MCP Tool: Multi-Cluster Ops & Hybrid Cloud Security

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.

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:

1. MCP Server : A compliant server that handles requests from MCP clients (AI assistants)
2. Tools Registry : Registers Kubernetes operations as MCP tools with schemas
3. Transport Layer : Supports stdio, SSE, and HTTP transport methods
4. Core Operations : Translates tool calls to Kubernetes API operations
5. Response Formatter : Converts Kubernetes responses to MCP-compliant responses

Request Flow

Dual Mode Operation

The tool operates in two modes:

1. CLI Mode : Direct command-line interface for executing Kubernetes operations
2. 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.0.0

The package is available on PyPI: https://pypi.org/project/kubectl-mcp-tool/1.0.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

# Test connection to Kubernetes
kubectl-mcp get pods

Usage with AI Assistants

Claude Desktop

Add the following to your Claude Desktop configuration:

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.cli"]
    }
  }
}

Cursor AI

Add the following to your Cursor AI configuration:

{
  "tools": [
    {
      "name": "kubectl-mcp",
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.cli"],
      "description": "A tool for interacting with Kubernetes clusters."
    }
  ]
}

Windsurf

Add the following to your Windsurf configuration:

{
  "extensions": [
    {
      "name": "kubectl-mcp",
      "description": "Kubernetes operations using MCP",
      "exec": {
        "command": "python",
        "args": ["-m", "kubectl_mcp_tool.cli"]
      }
    }
  ]
}

Prerequisites

1. kubectl installed and in your PATH
2. A valid kubeconfig file
3. Access to a Kubernetes cluster
4. 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.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.