kubectl-mcp-tool 1.3.0

A Model Context Protocol (MCP) server for Kubernetes

Kubectl MCP Server

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, HTTP/streamable-http)
• Integration with multiple AI assistants (Claude Desktop, Claude Code, Cursor, Windsurf)
• Multi-cluster support with context switching
• 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
• Command injection protection with input validation

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.1.1

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

# 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:

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.

Docker Image

If you prefer using Docker, a pre-built image is available on Docker Hub:

# Pull the latest image
docker pull rohitghumare64/kubectl-mcp-server:latest

Docker MCP Toolkit Integration

This image is compatible with Docker MCP Toolkit. The Toolkit provides a streamlined way to run MCP servers with Claude, Cursor, and other AI assistants.

Quick Setup with Docker MCP Toolkit:

1. Add the server to Docker MCP Toolkit:

   docker mcp server add kubectl-mcp-server rohitghumare64/kubectl-mcp-server:latest
   

2. Configure kubeconfig access:

   docker mcp server configure kubectl-mcp-server --volume "$HOME/.kube:/root/.kube:ro"
   

3. Enable the server:

   docker mcp server enable kubectl-mcp-server
   

4. Connect your AI client (e.g., Claude Desktop):

   docker mcp client connect claude
   

The server uses stdio transport by default for Docker MCP Toolkit compatibility.

Running the image (Standalone)

For SSE/HTTP transport (without Docker MCP Toolkit):

# SSE transport on port 8000
docker run -p 8081:8000 \
           -v $HOME/.kube:/root/.kube:ro \
           rohitghumare64/kubectl-mcp-server:latest \
           --transport sse --host 0.0.0.0 --port 8000

For stdio transport (for direct MCP client connections):

docker run -i \
           -v $HOME/.kube:/root/.kube:ro \
           rohitghumare64/kubectl-mcp-server:latest

• -i enables interactive mode for stdio transport
• -v $HOME/.kube:/root/.kube:ro mounts kubeconfig as read-only

Building a multi-architecture image (AMD64 & ARM64)

If you want to build and push a multi-arch image (so it runs on both x86_64 and Apple Silicon), use Docker Buildx:

# Ensure Buildx and QEMU are installed once per machine
# docker buildx create --name multiarch --use
# docker buildx inspect --bootstrap

# Build and push for linux/amd64 and linux/arm64
# (replace <your_username> if you're publishing to your own registry)

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t rohitghumare64/kubectl-mcp-server:latest \
  --push .

The published image will contain a manifest list with both architectures, and Docker will automatically pull the correct variant on each machine.

Configuration

The MCP server is allowed to access these paths to read your Kubernetes configuration:

run:
  volumes:
    - '{{kubectl-mcp-server.kubeconfig}}:/root/.kube'
config:
  description: The MCP server is allowed to access this path
  parameters:
    type: object
    properties:
      kubeconfig:
        type: string
        default:
          $HOME/.kube
    required:
      - kubeconfig

This configuration allows users to add their kubeconfig directory to the container, enabling the MCP server to authenticate with their Kubernetes cluster.

Transport Modes

The MCP server supports multiple transport protocols:

stdio (default)

Standard input/output transport, used by most MCP clients like Claude Desktop and Cursor:

python -m kubectl_mcp_tool.mcp_server --transport stdio

SSE (Server-Sent Events)

HTTP-based transport using Server-Sent Events:

python -m kubectl_mcp_tool.mcp_server --transport sse --host 0.0.0.0 --port 8000

HTTP / Streamable HTTP

Standard HTTP transport for clients that prefer JSON-RPC over HTTP:

python -m kubectl_mcp_tool.mcp_server --transport http --host 0.0.0.0 --port 8000
# or
python -m kubectl_mcp_tool.mcp_server --transport streamable-http --host 0.0.0.0 --port 8000

Command-Line Options

• --transport: Transport mode (stdio, sse, http, streamable-http). Default: stdio
• --host: Host to bind for network transports. Default: 0.0.0.0
• --port: Port for network transports. Default: 8000

Multi-Cluster Support

The MCP server provides full multi-cluster support through context management:

# List all available contexts
list_contexts

# Switch to a different cluster
switch_context --context_name production

# Get details about a specific context
get_context_details --context_name staging

# Set default namespace for a context
set_namespace_for_context --namespace kube-system --context_name production

For detailed monitoring features documentation, see Monitoring Guide.

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 with kubectl_mcp_tool.minimal_wrapper in your configuration. The minimal wrapper provides basic capabilities with simpler implementation.

1. 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"
         }
       }
     }
   }
   

2. Key Environment Variables

   • MCP_LOG_FILE: Path to log file (recommended to avoid stdout pollution)
   • MCP_DEBUG: Set to "1" for verbose logging
   • MCP_TEST_MOCK_MODE: Set to "1" to use mock data instead of real cluster
   • KUBECONFIG: Path to your Kubernetes config file
   • KUBECTL_MCP_LOG_LEVEL: Set to "DEBUG", "INFO", "WARNING", or "ERROR"

3. Testing the MCP Server You can test if the server is working correctly with:

   python -m kubectl_mcp_tool.simple_ping
   

   This 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 ~/Library/Application\ Support/Claude/claude_desktop_config.json (Windows: %APPDATA%\Claude\mcp.json):

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.mcp_server"], 
      "env": {
        "KUBECONFIG": "$HOME/.kube/config" // or whatever your path is for the config file
      }
    }
  }
}

Claude Code

Claude Code is Anthropic's CLI tool for coding with Claude. Add the following to ~/.config/claude-code/mcp.json:

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
      "env": {
        "KUBECONFIG": "/path/to/your/.kube/config"
      }
    }
  }
}

For detailed Claude Code integration instructions, see Claude Code Integration Guide.

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.mcp_server"],
      "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.mcp_server"],
      "env": {
        "KUBECONFIG": "/path/to/your/.kube/config"
      }
    }
  }
}

Automatic Configuration

For automatic configuration of all supported AI assistants, run the provided installation script:

bash install.sh