MCP Server Kubernetes for Claude Code: Setup & Config

What you can do with MCP Server Kubernetes in Claude Code

An existing-context Kubernetes bridge spanning diagnostics, resource changes, Helm, and tracing.

• Inspect pods and logs while diagnosing workload failures.
• Trace assistant-driven cluster operations through an OTLP backend.

Before you start: MCP Server Kubernetes in Claude Code

• Node.js and npx
• kubectl on PATH
• A valid kubeconfig with cluster access
• Helm v3 on PATH for Helm operations

Loads the standard kubeconfig and current kubectl context by default. Set ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS to true to disable designated destructive operations; this still permits creation and updates. Telemetry is optional and off by default.

MCP Server Kubernetes Claude Code configuration

1. Choose Claude Code configuration scope

   For MCP Server Kubernetes, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add MCP Server Kubernetes to Claude Code

   Use the mcp-server-kubernetes entry below in mcpServers. Keep MCP Server Kubernetes's documented stdio connection fields and your other Claude Code entries.

3. Check MCP Server Kubernetes in Claude Code

   MCP Server Kubernetes: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "mcp-server-kubernetes": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "mcp-server-kubernetes"
      ],
      "env": {}
    }
  }
}

claude mcp add-json --scope project 'mcp-server-kubernetes' '{"type":"stdio","command":"npx","args":["mcp-server-kubernetes"],"env":{}}'

MCP Server Kubernetes tools available to Claude Code

MCP Server Kubernetes's stored tool list documents 26 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

cleanup

For MCP Server Kubernetes's cleanup, review the permission request and arguments in Claude Code before approval.

Remove resources managed by the server.

kubectl_get

For MCP Server Kubernetes's kubectl_get, review the permission request and arguments in Claude Code before approval.

Retrieve Kubernetes objects by type, name, and optional namespace.

kubectl_describe

For MCP Server Kubernetes's kubectl_describe, review the permission request and arguments in Claude Code before approval.

Inspect detailed information about selected Kubernetes objects.

kubectl_apply

For MCP Server Kubernetes's kubectl_apply, review the permission request and arguments in Claude Code before approval.

Apply a YAML manifest supplied as text or a file.

kubectl_delete

For MCP Server Kubernetes's kubectl_delete, review the permission request and arguments in Claude Code before approval.

Delete resources selected by name, labels, type, or manifest.

kubectl_create

For MCP Server Kubernetes's kubectl_create, review the permission request and arguments in Claude Code before approval.

Create resources from files or supported creation subcommands.

kubectl_logs

For MCP Server Kubernetes's kubectl_logs, review the permission request and arguments in Claude Code before approval.

Read logs from workloads such as pods, deployments, and jobs.

kubectl_scale

For MCP Server Kubernetes's kubectl_scale, review the permission request and arguments in Claude Code before approval.

kubectl_patch

For MCP Server Kubernetes's kubectl_patch, review the permission request and arguments in Claude Code before approval.

kubectl_rollout

For MCP Server Kubernetes's kubectl_rollout, review the permission request and arguments in Claude Code before approval.

kubectl_context

For MCP Server Kubernetes's kubectl_context, review the permission request and arguments in Claude Code before approval.

kubectl_reconnect

For MCP Server Kubernetes's kubectl_reconnect, review the permission request and arguments in Claude Code before approval.

explain_resource

For MCP Server Kubernetes's explain_resource, review the permission request and arguments in Claude Code before approval.

install_helm_chart

For MCP Server Kubernetes's install_helm_chart, review the permission request and arguments in Claude Code before approval.

upgrade_helm_chart

For MCP Server Kubernetes's upgrade_helm_chart, review the permission request and arguments in Claude Code before approval.

uninstall_helm_chart

For MCP Server Kubernetes's uninstall_helm_chart, review the permission request and arguments in Claude Code before approval.

node_management

For MCP Server Kubernetes's node_management, review the permission request and arguments in Claude Code before approval.

port_forward

For MCP Server Kubernetes's port_forward, review the permission request and arguments in Claude Code before approval.

stop_port_forward

For MCP Server Kubernetes's stop_port_forward, review the permission request and arguments in Claude Code before approval.

exec_in_pod

For MCP Server Kubernetes's exec_in_pod, review the permission request and arguments in Claude Code before approval.

Run an executable and argument array in a container without shell interpretation.

list_api_resources

For MCP Server Kubernetes's list_api_resources, review the permission request and arguments in Claude Code before approval.

Enumerate resource APIs supported by the cluster.

kubectl_generic

For MCP Server Kubernetes's kubectl_generic, review the permission request and arguments in Claude Code before approval.

Run a kubectl command using supplied arguments and flags.

ping

For MCP Server Kubernetes's ping, review the permission request and arguments in Claude Code before approval.

Check whether the connection remains responsive.

cleanup_pods

For MCP Server Kubernetes's cleanup_pods, review the permission request and arguments in Claude Code before approval.

Clean up pods in documented problematic or completed states.

helm_template_apply

For MCP Server Kubernetes's helm_template_apply, review the permission request and arguments in Claude Code before approval.

Use template-based Helm installation to work around authentication issues.

helm_template_uninstall

For MCP Server Kubernetes's helm_template_uninstall, review the permission request and arguments in Claude Code before approval.

MCP Server Kubernetes: full stored tool descriptions

Troubleshooting MCP Server Kubernetes in Claude Code

• If MCP Server Kubernetes fails to start, check npx mcp-server-kubernetes (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• MCP Server Kubernetes uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires working cluster credentials and local kubectl.
• Known limitation: Non-destructive mode still allows resource changes.
• Known limitation: Secret masking does not cover log output.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions