Using Kubernetes MCP Server with Claude Code CLI

February 23, 2026 · View on GitHub

This guide shows you how to configure the Kubernetes MCP Server with Claude Code CLI.

Prerequisites: Complete the Getting Started with Kubernetes guide first to create a ServiceAccount and kubeconfig file.

Quick Setup

Add the MCP server using the claude mcp add-json command:

claude mcp add-json kubernetes-mcp-server \
  '{"command":"npx","args":["-y","kubernetes-mcp-server@latest","--read-only"],"env":{"KUBECONFIG":"'${HOME}'/.kube/mcp-viewer.kubeconfig"}}' \
  -s user

What this does:

  • Adds the Kubernetes MCP Server to your Claude Code configuration
  • Uses npx to automatically download and run the latest version
  • Enables read-only mode for safety
  • Uses the kubeconfig file you created in the Getting Started guide
  • -s user makes it available in all your projects

Manual Configuration (Alternative)

If you prefer to edit the config file manually:

Location: ~/.config/claude-code/config.toml

[[mcp_servers]]
name = "kubernetes-mcp-server"
command = "npx"
args = [
    "-y",
    "kubernetes-mcp-server@latest",
    "--read-only"
]

[mcp_servers.env]
KUBECONFIG = "/home/YOUR_USERNAME/.kube/mcp-viewer.kubeconfig"

Important: Replace /home/YOUR_USERNAME/ with your actual home directory path.

Verify Connection

After adding the MCP server, verify it's connected:

claude mcp list

Expected output:

Checking MCP server health...

kubernetes-mcp-server: npx -y kubernetes-mcp-server@latest --read-only - ✓ Connected

Using the MCP Server

Once connected, interact with your Kubernetes cluster using natural language! Claude will use the Kubernetes MCP Server to fetch and display the relevant information from your cluster:

> List all namespaces in my cluster 

● I'll list all the namespaces in your Kubernetes cluster.
  ⎿  APIVERSION   KIND        NAME                 STATUS   AGE   LABELS
     v1           Namespace   default              Active   77m   kubernetes.io/metadata.name=default
     v1           Namespace   kube-node-lease      Active   77m   kubernetes.io/metadata.name=kube-node-lease
     … +4 lines (ctrl+o to expand)

● Your cluster has 6 namespaces:

  1. default - The default namespace for resources without a specified namespace
  2. kube-node-lease - Used for node heartbeat/lease objects
  3. kube-public - Publicly accessible namespace, typically for cluster information
  4. kube-system - System namespace for Kubernetes control plane components
  5. local-path-storage - Likely used for local storage provisioning
  6. mcp - Custom namespace (created ~75 minutes ago)

  All namespaces are in Active status and the cluster appears to be running for about 77 minutes.

Configuration Options

Common command-line flags you can add to the args array:

FlagDescription
--read-onlyEnable read-only mode (recommended)
--kubeconfig <path>Path to kubeconfig file (or use KUBECONFIG env var)
--config <path>Path to TOML config file (for advanced options like server_instructions)

Claude Code supports MCP Tool Search, a feature that dynamically loads tools based on relevance to your query. This helps when you have many MCP servers connected.

You can configure server_instructions to help Claude know when to use this server's tools. See the Server Instructions section in the main README for details.

Next Steps