Skip to content

rohitg00/kubectl-mcp-server

BranchesTags

Repository files navigation

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.

License: MIT Python Kubernetes MCP PyPI version

🎥 Live Demo - Watch kubectl-mcp-tool in Action with Claude!

Claude MCP

🎥 Live Demo - Watch kubectl-mcp-tool in Action with Cursor!

Cursor MCP

🎥 Live Demo - Watch kubectl-mcp-tool in Action with Windsurf!

Windsurf MCP

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

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

Running the image

The server inside the container listens on port 8000. Bind any free host port to 8000 and mount your kubeconfig:

# Replace 8081 with any free port on your host
# Mount your local ~/.kube directory for cluster credentials

docker run -p 8081:8000 \
           -v $HOME/.kube:/root/.kube \
           rohitghumare64/kubectl-mcp-server:latest
  • -p 8081:8000 maps host port 8081 → container port 8000.
  • -v $HOME/.kube:/root/.kube mounts your kubeconfig so the server can reach the cluster.

Building the image locally

To build the image from source instead of pulling from Docker Hub:

git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server

docker build -t kubectl-mcp-server .

# Run the locally-built image (same run flags as above)
docker run -p 8081:8000 -v $HOME/.kube:/root/.kube kubectl-mcp-server

This yields identical functionality but lets you modify the codebase before building.

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 ~/.config/claude/mcp.json (Windows: %APPDATA%\Claude\mcp.json):

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
      "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.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

About

Chat with your Kubernetes Cluster using AI tools and IDEs like Claude and Cursor!

createmvps.app/mcp-rules

Topics

kubernetes devops ai deployment mcp kubernetes-cluster llms genai mcp-server

Resources

Readme

License

MIT license
Activity

Stars

645 stars

Watchers

9 watching

Forks

114 forks
Report repository

Releases

1 tags

Sponsor this project

 
Learn more about GitHub Sponsors

Packages

No packages published

Contributors 4

Languages