kubectl-mcp-tool 1.0.0

A Model Context Protocol (MCP) server for Kubernetes

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

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/         # Python implementation
│   ├── cli.py                # CLI entry point
│   ├── mcp_server.py         # MCP server implementation
│   ├── core/                 # Core functionality
│   ├── security/             # Security operations
│   └── monitoring/           # Monitoring functionality
├── python_tests/             # Python tests
├── compatible_servers/       # Compatible MCP server implementations
│   ├── cursor/               # Cursor-compatible servers
│   ├── windsurf/             # Windsurf-compatible servers
│   ├── minimal/              # Minimal server implementations
│   └── generic/              # Generic MCP servers
└── docs/                     # Documentation
    ├── cursor/               # Cursor integration docs
    ├── windsurf/             # Windsurf integration docs
    └── claude/               # Claude integration docs

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.