Kubernetes MCP Server

How to use

You connect to the Kubernetes MCP server from your MCP client to perform Kubernetes and OpenShift operations. You can work with generic resources, pods (including logs, execution, and top metrics), namespaces, events, and OpenShift projects, as well as Helm charts and KubeVirt resources. When multi-cluster access is enabled, you can target specific clusters via contexts in your kubeconfig. You can also enable observability and telemetry to monitor the server’s behavior and performance.

How to install

Follow these concrete steps to install and start using the Kubernetes MCP server.

# Prerequisites: ensure Node.js and npm exist if you plan to use npx
# You may also run a binary or uvx-based installation as an alternative

# Using npx (fastest way to get started)
npx kubernetes-mcp-server@latest --help

# Start the server with npx (example; customize via config as needed)
npx kubernetes-mcp-server@latest

# Using uvx (if you have uv and Python installed)
uvx kubernetes-mcp-server@latest --help

# Start the server with uvx (example)
uvx kubernetes-mcp-server@latest

# Run via the latest release binary
./kubernetes-mcp-server --help
# Then start the server directly
./kubernetes-mcp-server

# Claude Desktop example configuration (in claude_desktop_config.json)
``` json
{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "-y",
        "kubernetes-mcp-server@latest"
      ]
    }
  }
}
```

# Cursor extension example (mcp.json)
```json
{
  "mcpServers": {
    "kubernetes-mcp-server": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest"]
    }
  }
}
```

# Goose CLI example (config.yaml)
```yaml
extensions:
  kubernetes:
    command: npx
    args:
      - -y
      - kubernetes-mcp-server@latest

Configuration options at a glance

Configure the MCP server using CLI arguments or a TOML config file. You can set port, logging level, kubeconfig location, multi-cluster behavior, and more. See the Configuration Reference for full details.

Additional usage notes

If you have a multi-cluster kubeconfig, you can selectively target clusters per operation. You can enable or disable specific toolsets to control which Kubernetes capabilities are exposed to your tooling, reducing context size for AI agents. You can also enable observability with optional tracing and metrics.

Prompts and practical helpers

Prompts and helpers are available to perform common tasks like health checks, cluster health, and troubleshooting for workloads and resources. These prompts help you guide the MCP server to perform tasks efficiently.

Helm Chart

A Helm Chart is available to simplify deployment of the Kubernetes MCP server. Install using: `` helm install kubernetes-mcp-server oci://ghcr.io/containers/charts/kubernetes-mcp-server ``

Community and development

Join the community to share feedback and get help. Development can be done by building locally and running with inspector tooling to observe MCP server behavior.

Security and observability

The MCP server supports optional observability features and secures responses by redacting sensitive data before sending to clients.

Measuring success

Use the SPI-like telemetry and real-time statistics endpoint to verify health and performance during operation.

Notes and caveats

The server is designed as a native Go-based MCP server with direct API interactions to Kubernetes, avoiding reliance on external CLI wrappers for Kubernetes or Helm commands.

cluster-health-check

Perform comprehensive health assessment of Kubernetes/OpenShift cluster with optional namespace scoping and event inclusion.

vm-troubleshoot

Generate a step-by-step troubleshooting guide for diagnosing VirtualMachine issues in KubeVirt.

config_view

View the current Kubernetes kubeconfig content and context.

events_list

List Kubernetes events for debugging and troubleshooting in the current cluster.

namespaces_list

List all Kubernetes namespaces in the current cluster.

projects_list

List all OpenShift projects in the current cluster.

pods_list

List all pods across all namespaces in the cluster.

pods_get

Get details for a specific pod by name in a namespace.

pods_delete

Delete a specific pod by name in a namespace.

pods_log

Fetch logs from a pod container with optional previous logs and tail lines.

pods_exec

Execute a command inside a pod container for shell access.

pods_run

Run a new pod with a specific container image in a namespace.

pods_top

Show resource usage for pods using the Metrics Server.

resources_list

List Kubernetes resources by apiVersion and kind, with optional namespace and label filtering.

resources_get

Get a specific resource by apiVersion, kind, and name.

resources_create_or_update

Create or update a Kubernetes resource from a YAML/JSON representation.

resources_delete

Delete a Kubernetes resource by apiVersion, kind, and name.

resources_scale

Get or update the scale of a scalable resource.

helm_install

Install a Helm chart as a release in a namespace.

helm_list

List Helm releases in a namespace or all namespaces.

helm_uninstall

Uninstall a Helm release from a namespace.

kcp_workspaces_list

List available kcp workspaces in the current cluster.

kcp_workspace_describe

Describe a specific kcp workspace.

kiali_mesh_graph

Return topology and health metrics for Istio mesh in a namespace.

kiali_manage_istio_config

Create, patch, or delete Istio configuration objects.

kiali_get_resource_details

Get details for Kubernetes resources within the mesh.

kiali_get_metrics

Retrieve metrics for resources within a namespace.

kiali_workload_logs

Get logs for a workload's pods in a namespace.

kiali_get_traces

Get traces for resources or a specific trace by ID.

vm_clone

Clone a KubeVirt VirtualMachine.

vm_create

Create a VirtualMachine with specified configuration.

vm_lifecycle

Manage VirtualMachine lifecycle actions like start, stop, or restart.