mcp-kubernetes

mcp-kubernetes provides an MCP server that lets AI assistants interact with a Kubernetes cluster through natural language. It translates requests into kubectl operations and returns results in a structured format suitable for downstream AI tools. By default, it exposes a unified call_kubectl tool that can execute any kubectl command via a single interface, minimizing context switching while preserving full Kubernetes capabilities. You can also enable the legacy mode to access multiple specialized kubectl tools if you prefer more granular tool separation.

To use it, configure Claude Desktop, Cursor, GitHub Copilot, or other supported clients to connect to the MCP server. The server supports environments where your kubeconfig is mounted into the container, letting the AI translate prompts like listing resources, inspecting pods, or applying manifests into concrete kubectl commands. You can set access levels to limit operations (readonly, readwrite, admin) to match your security needs.

Prerequisites:

• Docker installed on the host machine
• Access to a Kubernetes cluster and a kubeconfig file
• Optional: kubectl and helm installed locally if you plan to use the Local installation path

Docker (recommended):

1. Ensure your kubeconfig is available on the host, e.g. ~/.kube/config
2. Run the MCP Kubernetes container with your kubeconfig mounted:

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=/home/username/.kube/config,dst=/home/mcp/.kube/config",
        "ghcr.io/azure/mcp-kubernetes"
      ]
    }
  }
}

3. Adjust the path to your kubeconfig as needed. You can also set environment variables like USE_LEGACY_TOOLS to switch between unified and legacy tool sets.

Local (if you prefer building and running locally):

1. Install prerequisites: kubectl, helm (optional) as needed for Kubernetes interactions.
2. Build or obtain the mcp-kubernetes binary, then run it with appropriate flags to connect to your cluster (e.g., provide --transport if needed).
3. Point your MCP client configuration to the local binary and provide KUBECONFIG via env if required.

Environment variables:

• KUBECONFIG: Path to your kubeconfig file (e.g. /home/user/.kube/config)
• USE_LEGACY_TOOLS: Set to true to enable multiple specialized kubectl tools instead of the unified call_kubectl tool (default: false)

Command line options (examples):

• --transport: stdio, sse, or streamable-http (default: stdio)
• --access-level: readonly, readwrite, or admin (default: readonly)
• --port / --host: network binding for the server (defaults depend on transport)

Common issues:

• Ensure kubeconfig is accessible to the container or host, and that the kubeconfig context points to the desired cluster
• When using legacy tools, ensure USE_LEGACY_TOOLS is set in the MCP config
• If kubectl is not found in PATH when using local mode, install it and verify the PATH
• For secure deployments, limit access levels and consider using transport methods that suit your environment