Kubernetes MCP Server: Setup, Configuration, and Production Usage

Quick Answer

• What it is: mcp-server-kubernetes is an MCP (Model Context Protocol) server that lets AI assistants like Claude Desktop manage Kubernetes clusters using natural language commands.
• First check: Ensure kubectl get nodes works from your terminal before installing the MCP server — it uses your existing kubeconfig.
• Minimal install: Run npm install -g mcp-server-kubernetes globally, then configure Claude Desktop with the npx command shown below.
• Production boundary: Set ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true for read-only access; never use this in production without a dedicated read-only ServiceAccount and isolated namespace.
• Version note: Requires Node.js 18+ and access to a Kubernetes API server (any version compatible with your kubeconfig context).

What Problem It Solves

DevOps engineers, platform engineers, and SRE teams often need to perform routine Kubernetes operations — checking pod status, viewing logs, creating resources, deploying Helm charts — without switching contexts between a terminal and an AI assistant. The Kubernetes MCP Server bridges this gap by exposing Kubernetes API operations as MCP tools that AI assistants can call.

This is particularly useful for:

• Daily cluster巡检 (health checks, resource monitoring)
• Quick resource creation from natural language descriptions
• Log viewing and troubleshooting
• Helm chart deployment and management
• Reducing context switching during incident response

It is not suitable for high-throughput automation, low-latency operations, or environments requiring strict audit trails.

Installation and Quick Start

Prerequisites

• Node.js 18 or later
• A working Kubernetes cluster with kubectl configured
• Claude Desktop (or any MCP-compatible client)

Install the Server

BASH
npm install -g mcp-server-kubernetes

This installs the server globally. Verify with:

BASH
which mcp-server-kubernetes

Configure Claude Desktop

Add the following to your Claude Desktop configuration file (claude_desktop_config.json):

JSON
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "mcp-server-kubernetes"
      ],
      "env": {
        "KUBECONFIG": "/path/to/.kube/config",
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "false"
      }
    }
  }
}

Replace /path/to/.kube/config with the actual path to your kubeconfig file. Set ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS to "true" for read-only mode.

Test the Connection

After restarting Claude Desktop, ask: "List all pods in the default namespace." If you see pod information, the setup is working.

Parameters and Environment Variables

The ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS environment variable is the primary safety mechanism. When enabled, the server will reject destructive operations like delete, scale down, or rollback. However, note that "create" operations are still permitted — so a user could still create a pod that consumes cluster resources.

Common Errors and Fixes

Error: connect ECONNREFUSED 127.0.0.1:6443

Cause: The Kubernetes API server is not running, or the kubeconfig points to an incorrect address.

Solution:

1. Verify the API server is accessible: kubectl get nodes
2. Check your kubeconfig: kubectl config view --minify
3. Ensure the KUBECONFIG environment variable in your MCP configuration points to the correct file

Error: Forbidden: user cannot list pods in namespace default

Cause: The kubeconfig user lacks sufficient RBAC permissions.

Solution:

1. Check current permissions: kubectl auth can-i list pods --namespace default
2. Switch to a context with appropriate permissions: kubectl config use-context <context-name>
3. Create a dedicated ServiceAccount with a read-only ClusterRole for production use

Error: Helm release already exists

Cause: A Helm release with the same name already exists in the target namespace.

Solution:

1. List existing releases: helm list -n <namespace>
2. Use a different release name in your request
3. Uninstall the existing release first if you want to replace it

Error: timeout waiting for condition

Cause: An operation (typically resource creation or deletion) timed out, often due to insufficient cluster resources.

Solution:

1. Check for pending pods: kubectl get pods --all-namespaces | grep Pending
2. Verify cluster resource availability: kubectl describe nodes
3. Increase the MCP server timeout by setting MCP_TIMEOUT environment variable (if supported by your client)

Production Notes and Security Checks

Running the Kubernetes MCP Server in production requires careful security considerations:

Critical Limitations

Recommended Production Configuration

JSON
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "mcp-server-kubernetes"
      ],
      "env": {
        "KUBECONFIG": "/path/to/readonly-kubeconfig",
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

Create a dedicated ServiceAccount with a read-only ClusterRole:

BASH
kubectl create serviceaccount mcp-readonly -n mcp-system
kubectl create clusterrolebinding mcp-readonly-binding \
  --clusterrole=view \
  --serviceaccount=mcp-system:mcp-readonly

Export the ServiceAccount's kubeconfig and use that file as the KUBECONFIG value.

FAQ

Q: How do I ensure read-only access to a production cluster?

A: Set ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true and use a kubeconfig that only has get, list, and watch permissions. Create a dedicated ServiceAccount bound to the view ClusterRole, and export its kubeconfig for use with the MCP server.

Q: Can I connect to multiple Kubernetes clusters simultaneously?

A: Each MCP Server instance uses a single kubeconfig context. To work with multiple clusters, start separate MCP Server instances with different KUBECONFIG environment variables, and register each as a separate MCP server in your Claude Desktop configuration.

Q: How do I audit operations performed through the MCP server?

A: The MCP Server itself does not provide audit logging. Enable Kubernetes API audit logging on your cluster using an audit policy. Alternatively, wrap the MCP Server process with a logging proxy that records all API calls. For critical environments, consider using a separate monitoring tool to capture all kubectl-equivalent operations.