mcp-kubernetes

The mcp-kubernetes-server acts as a bridge between AI assistants that support the Model Context Protocol (MCP) and your Kubernetes cluster. It translates natural language requests into kubectl commands or Kubernetes API calls, executes them against your cluster, and returns structured results that can be consumed by your AI assistant. With this server, you can ask questions about resource status, fetch resource details, and perform read-only or write operations depending on your configuration and the capabilities you enable.

To use it, configure the MCP server in your AI client (as shown in the Docker example in the README). Once started, you can issue natural language prompts such as asking for the status of a deployment, listing pods in a namespace, or diagnosing issues with a pod. The server exposes tools for both read operations (k8s_get, k8s_describe, k8s_logs, k8s_events) and command execution (kubectl, helm). Depending on your transport (stdio, sse, or streamable-http), the AI client will manage the connection and handle responses from the server.

Prerequisites:

• A working Kubernetes cluster
• A kubeconfig file configured to access your cluster
• kubectl in your PATH
• helm in your PATH
• Python 3.11 or newer for direct uvx usage (optional)

Option 1: Docker (recommended if you want a quick start)

1. Ensure Docker is installed and running.
2. Place your kubeconfig at the path referenced in the docker command (adjust /home/username/.kube/config as needed).
3. Run the server using the example configuration:

# Ensure environment is ready, then start the container with your kubeconfig bind-mount

Option 2: UVX (Python/uv) (requires Python 3.11+ and uv)

1. Install uv if it's not installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install kubectl and helm if not already installed (as described in prerequisites).
3. Run the server with uvx using the provided command:

uvx mcp-kubernetes-server

Option 3: Kubernetes cluster prerequisites (for both methods)

• Ensure kubeconfig is available and points to the correct cluster/context
• Ensure kubectl can access the cluster (kubectl get nodes should work)
• Optionally install Helm if you plan to manage charts via the server

Configuration example (Docker):

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

• The KUBECONFIG environment variable can be used to specify your kubeconfig path if you prefer not to bind-mount the file.
• For Docker setups, ensure the kubeconfig path used in the mount matches your actual kubeconfig location.
• The server supports multiple tools (kubectl, helm, and various k8s read tools). You can adjust permissions to allow or restrict write/delete capabilities using the server’s options.
• If you encounter transport-related connection issues, verify your MCP client is configured to use stdio, SSE, or streamable-http as appropriate for your setup.
• Common debugging tips: check that kubectl works from the host, ensure the container has network access to the cluster API server, and verify that the container’s mounted kubeconfig has the correct permissions.