Kubernetes MCP Server

✨ Features | 🚀 Getting Started | 🎥 Demos | ⚙️ Configuration | 🛠️ Tools | 💬 Community | 🧑‍💻 Development

kubernetes-mcp-server.mp4

✨ Features

A powerful and flexible Kubernetes Model Context Protocol (MCP) server implementation with support for Kubernetes and OpenShift.

• ✅ Configuration:
  • Automatically detect changes in the Kubernetes configuration and update the MCP server.
  • View and manage the current Kubernetes .kube/config or in-cluster configuration.
• ✅ Generic Kubernetes Resources: Perform operations on any Kubernetes or OpenShift resource.
  • Any CRUD operation (Create or Update, Get, List, Delete).
• ✅ Pods: Perform Pod-specific operations.
  • List pods in all namespaces or in a specific namespace.
  • Get a pod by name from the specified namespace.
  • Delete a pod by name from the specified namespace.
  • Show logs for a pod by name from the specified namespace.
  • Top gets resource usage metrics for all pods or a specific pod in the specified namespace.
  • Exec into a pod and run a command.
  • Run a container image in a pod and optionally expose it.
• ✅ Namespaces: List Kubernetes Namespaces.
• ✅ Events: View Kubernetes events in all namespaces or in a specific namespace.
• ✅ Projects: List OpenShift Projects.
• ☸️ Helm:
  • Install a Helm chart in the current or provided namespace.
  • List Helm releases in all namespaces or in a specific namespace.
  • Uninstall a Helm release in the current or provided namespace.
• 🔧 Tekton: Tekton-specific operations that complement generic Kubernetes resource management.
  • Pipeline: Start a Tekton Pipeline by creating a PipelineRun.
  • PipelineRun: Restart a PipelineRun with the same spec.
  • Task: Start a Tekton Task by creating a TaskRun.
  • TaskRun: Restart a TaskRun with the same spec, and retrieve TaskRun logs via pod resolution.
• 🔭 Observability: Optional OpenTelemetry distributed tracing and metrics with custom sampling rates. Includes /stats endpoint for real-time statistics. See OTEL.md.

Unlike other Kubernetes MCP server implementations, this IS NOT just a wrapper around kubectl or helm command-line tools. It is a Go-based native implementation that interacts directly with the Kubernetes API server.

There is NO NEED for external dependencies or tools to be installed on the system. If you're using the native binaries you don't need to have Node or Python installed on your system.

• ✅ Lightweight: The server is distributed as a single native binary for Linux, macOS, and Windows.
• ✅ High-Performance / Low-Latency: Directly interacts with the Kubernetes API server without the overhead of calling and waiting for external commands.
• ✅ Multi-Cluster: Can interact with multiple Kubernetes clusters simultaneously (as defined in your kubeconfig files).
• ✅ Cross-Platform: Available as a native binary for Linux, macOS, and Windows, as well as an npm package, a Python package, and container/Docker image.
• ✅ Configurable: Supports command-line arguments, TOML configuration files, and environment variables.
• ✅ Well tested: The server has an extensive test suite to ensure its reliability and correctness across different Kubernetes environments.
• 📚 Documentation: Comprehensive user documentation including setup guides, configuration reference, and observability.

🚀 Getting Started

Requirements

• Access to a Kubernetes cluster.

Claude Code

Follow the dedicated Claude Code getting started guide in our user documentation.

For a secure production setup with dedicated ServiceAccount and read-only access, also review the Kubernetes setup guide.

Claude Desktop

Using npx

If you have npm installed, this is the fastest way to get started with kubernetes-mcp-server on Claude Desktop.

Open your claude_desktop_config.json and add the mcp server to the list of mcpServers:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest"]
    }
  }
}

VS Code / VS Code Insiders

Install the Kubernetes MCP server extension in VS Code Insiders by pressing the following link:

Alternatively, you can install the extension manually by running the following command:

# For VS Code
code --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'
# For VS Code Insiders
code-insiders --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'

Cursor

Install the Kubernetes MCP server extension in Cursor by pressing the following link:

Alternatively, you can install the extension manually by editing the mcp.json file:

{
  "mcpServers": {
    "kubernetes-mcp-server": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest"]
    }
  }
}

Goose CLI

Goose CLI is the easiest (and cheapest) way to get rolling with artificial intelligence (AI) agents.

Using npm

If you have npm installed, this is the fastest way to get started with kubernetes-mcp-server.

Open your goose config.yaml and add the mcp server to the list of mcpServers:

extensions:
  kubernetes:
    command: npx
    args:
      - -y
      - kubernetes-mcp-server@latest

🎥 Demos

Diagnosing and automatically fixing an OpenShift Deployment

Demo showcasing how Kubernetes MCP server is leveraged by Claude Desktop to automatically diagnose and fix a deployment in OpenShift without any user assistance.

kubernetes-mcp-server-fix-openshift-deployment.mp4

Vibe Coding a simple game and deploying it to OpenShift

In this demo, I walk you through the process of Vibe Coding a simple game using VS Code and how to leverage Podman MCP server and Kubernetes MCP server to deploy it to OpenShift.

Supercharge GitHub Copilot with Kubernetes MCP Server in VS Code - One-Click Setup!

In this demo, I'll show you how to set up Kubernetes MCP server in VS code just by clicking a link.

⚙️ Configuration

The Kubernetes MCP server can be configured using command line (CLI) arguments.

You can run the CLI executable either by using npx, uvx, or by downloading the latest release binary.

# Run the Kubernetes MCP server using npx (in case you have npm and node installed)
npx kubernetes-mcp-server@latest --help

# Run the Kubernetes MCP server using uvx (in case you have uv and python installed)
uvx kubernetes-mcp-server@latest --help

# Run the Kubernetes MCP server using the latest release binary
./kubernetes-mcp-server --help

Configuration Options

Option	Description
--port	Starts the MCP server in Streamable HTTP mode (path /mcp) and Server-Sent Event (SSE) (path /sse) mode and listens on the specified port .
--log-level	Sets the logging level (values from 0-9). Similar to kubectl logging levels.
--config	(Optional) Path to the main TOML configuration file. See Configuration Reference for details.
--config-dir	(Optional) Path to drop-in configuration directory. Files are loaded in lexical (alphabetical) order. Defaults to conf.d relative to the main config file if --config is specified. See Configuration Reference for details.
--kubeconfig	Path to the Kubernetes configuration file. If not provided, it will try to resolve the configuration (in-cluster, default location, etc.).
--list-output	Output format for resource list operations (one of: yaml, table) (default "table")
--read-only	If set, the MCP server will run in read-only mode, meaning it will not allow any write operations (create, update, delete) on the Kubernetes cluster. This is useful for debugging or inspecting the cluster without making changes.
--disable-destructive	If set, the MCP server will disable all destructive operations (delete, update, etc.) on the Kubernetes cluster. This is useful for debugging or inspecting the cluster without accidentally making changes. This option has no effect when --read-only is used.
--stateless	If set, the MCP server will run in stateless mode, disabling tool and prompt change notifications. This is useful for container deployments, load balancing, and serverless environments where maintaining client state is not desired.
--toolsets	Comma-separated list of toolsets to enable. Check the 🛠️ Tools and Functionalities section for more information.
--disable-multi-cluster	If set, the MCP server will disable multi-cluster support and will only use the current context from the kubeconfig file. This is useful if you want to restrict the MCP server to a single cluster.
--cluster-provider	Cluster provider strategy to use (one of: kubeconfig, in-cluster, kcp, disabled). If not set, the server will auto-detect based on the environment.

Note: Most CLI options have equivalent TOML configuration fields. The --disable-multi-cluster flag is equivalent to setting cluster_provider_strategy = "disabled" in TOML. See the Configuration Reference for all TOML options.

TOML Configuration Files

For complex or persistent configurations, use TOML configuration files instead of CLI arguments:

kubernetes-mcp-server --config /etc/kubernetes-mcp-server/config.toml

Example configuration:

log_level = 2
read_only = true
toolsets = ["core", "config", "helm", "kubevirt"]

# Deny access to sensitive resources
[[denied_resources]]
group = ""
version = "v1"
kind = "Secret"

[telemetry]
endpoint = "http://localhost:4317"

For comprehensive TOML configuration documentation, including:

• All configuration options and their defaults
• Drop-in configuration files for modular settings
• Dynamic configuration reload via SIGHUP
• Denied resources for restricting access to sensitive resource types
• Server instructions for MCP Tool Search
• Custom MCP prompts
• OAuth/OIDC authentication for HTTP mode (Keycloak, Microsoft Entra ID)

See the Configuration Reference.

📊 MCP Logging

The server supports the MCP logging capability, allowing clients to receive debugging information via structured log messages. Kubernetes API errors are automatically categorized and logged to clients with appropriate severity levels. Sensitive data (tokens, keys, passwords, cloud credentials) is automatically redacted before being sent to clients.

See the MCP Logging Guide.

🛠️ Tools and Functionalities

The Kubernetes MCP server supports enabling or disabling specific groups of tools and functionalities (tools, resources, prompts, and so on) via the --toolsets command-line flag or toolsets configuration option. This allows you to control which Kubernetes functionalities are available to your AI tools. Enabling only the toolsets you need can help reduce the context size and improve the LLM's tool selection accuracy.

Validated Kubernetes Ecosystem Projects

The following CNCF and Kubernetes ecosystem projects are covered by automated evaluation scenarios in evals/tasks. Most scenarios work with just the core toolset. The dedicated toolsets below are optional and only needed for the project-specific scenarios noted.

Project	Optional toolset(s)	Eval scenarios
Helm	helm	3
Istio	kiali	5
Kiali	kiali	16
Kubernetes	-	32
KubeVirt	kubevirt, tekton	19
Tekton	tekton	9

Available Toolsets

The following sets of tools are available (toolsets marked with ✓ in the Default column are enabled by default):

Toolset	Description	Default
config	View and manage the current local Kubernetes configuration (kubeconfig)	✓
core	Most common tools for Kubernetes management (Pods, Generic Resources, Events, etc.)	✓
helm	Tools for managing Helm charts and releases
kcp	Manage kcp workspaces and multi-tenancy features
kiali	Most common tools for managing Kiali, check the Kiali documentation for more details.
kubevirt	KubeVirt virtual machine management tools, check the KubeVirt documentation for more details.
netobserv	Network observability tools backed by the NetObserv console plugin API (flows, metrics, export). Check the NetObserv documentation for more details.
tekton	Tekton pipeline management tools for Pipelines, PipelineRuns, Tasks, and TaskRuns.

Tools

In case multi-cluster support is enabled (default) and you have access to multiple clusters, all applicable tools will include an additional context argument to specify the Kubernetes context (cluster) to use for that operation.

cluster-diagnostics

• nodes_debug_exec - Run commands on an OpenShift node using a privileged debug pod with comprehensive troubleshooting utilities. The debug pod uses the UBI9 toolbox image which includes: systemd tools (systemctl, journalctl), networking tools (ss, ip, ping, traceroute, nmap), process tools (ps, top, lsof, strace), file system tools (find, tar, rsync), and debugging tools (gdb). The host filesystem is mounted at /host, allowing commands to chroot /host if needed to access node-level resources.
  • command (array) (required) - Command to execute on the node. All standard debugging utilities from the UBI9 toolbox are available. The host filesystem is mounted at /host - use 'chroot /host ' to access node-level resources, or run commands directly in the toolbox environment. Provide each argument as a separate array item (e.g. ['chroot', '/host', 'systemctl', 'status', 'kubelet'] or ['journalctl', '-u', 'kubelet', '--since', '1 hour ago']).
  • image (string) - Container image to use for the debug pod (optional). Defaults to registry.access.redhat.com/ubi9/toolbox:latest which provides comprehensive debugging and troubleshooting utilities.
  • namespace (string) - Namespace to create the temporary debug pod in (optional, defaults to the current namespace or 'default').
  • node (string) (required) - Name of the node to debug (e.g. worker-0).
  • timeout_seconds (integer) - Maximum time to wait for the command to complete before timing out (optional, defaults to 60 seconds).

config

• configuration_contexts_list - List all available context names and associated server urls from the kubeconfig file

• targets_list - List all available targets

• configuration_view - Get the current Kubernetes configuration content as a kubeconfig YAML

  • minified (boolean) - Return a minified version of the configuration. If set to true, keeps only the current-context and the relevant pieces of the configuration for that context. If set to false, all contexts, clusters, auth-infos, and users are returned in the configuration. (Optional, default true)

core

• events_list - List Kubernetes events (warnings, errors, state changes) for debugging and troubleshooting in the current cluster from all namespaces

  • fieldSelector (string) - Optional Kubernetes field selector to filter events by field values (e.g. 'type=Warning', 'involvedObject.name=my-pod'). Supported fields: involvedObject.kind, involvedObject.name, involvedObject.namespace, involvedObject.uid, involvedObject.apiVersion, involvedObject.resourceVersion, involvedObject.fieldPath, reason, reportingComponent, source, type. See https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
  • namespace (string) - Optional Namespace to retrieve the events from. If not provided, will list events from all namespaces

• namespaces_list - List all the Kubernetes namespaces in the current cluster

  • fieldSelector (string) - Optional Kubernetes field selector to filter namespaces by field values (e.g. 'metadata.name=default', 'status.phase=Active'). Supported fields: metadata.name, status.phase. See https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/

• projects_list - List all the OpenShift projects in the current cluster

• nodes_log - Get logs from a Kubernetes node (kubelet, kube-proxy, or other system logs). This accesses node logs through the Kubernetes API proxy to the kubelet

  • name (string) (required) - Name of the node to get logs from
  • query (string) (required) - query specifies services(s) or files from which to return logs (required). Example: "kubelet" to fetch kubelet logs, "/" to fetch a specific log file from the node (e.g., "/var/log/kubelet.log" or "/var/log/kube-proxy.log")
  • tailLines (integer) - Number of lines to retrieve from the end of the logs (Optional, 0 means all logs)

• nodes_stats_summary - Get detailed resource usage statistics from a Kubernetes node via the kubelet's Summary API. Provides comprehensive metrics including CPU, memory, filesystem, and network usage at the node, pod, and container levels. On systems with cgroup v2 and kernel 4.20+, also includes PSI (Pressure Stall Information) metrics that show resource pressure for CPU, memory, and I/O. See https://kubernetes.io/docs/reference/instrumentation/understand-psi-metrics/ for details on PSI metrics

  • name (string) (required) - Name of the node to get stats from

• nodes_top - List the resource consumption (CPU and memory) as recorded by the Kubernetes Metrics Server for the specified Kubernetes Nodes or all nodes in the cluster

  • label_selector (string) - Kubernetes label selector (e.g. 'node-role.kubernetes.io/worker=') to filter nodes by label (Optional, only applicable when name is not provided)
  • name (string) - Name of the Node to get the resource consumption from (Optional, all Nodes if not provided)

• pods_list - List all the Kubernetes pods in the current cluster from all namespaces

  • fieldSelector (string) - Optional Kubernetes field selector to filter pods by field values (e.g. 'status.phase=Running', 'spec.nodeName=node1'). Supported fields: metadata.name, metadata.namespace, spec.nodeName, spec.restartPolicy, spec.schedulerName, spec.serviceAccountName, status.phase (Pending/Running/Succeeded/Failed/Unknown), status.podIP, status.nominatedNodeName. Note: CrashLoopBackOff is a container state, not a pod phase, so it cannot be filtered directly. See https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
  • labelSelector (string) - Optional Kubernetes label selector (e.g. 'app=myapp,env=prod' or 'app in (myapp,yourapp)'), use this option when you want to filter the pods by label

• pods_list_in_namespace - List all the Kubernetes pods in the specified namespace in the current cluster

  • fieldSelector (string) - Optional Kubernetes field selector to filter pods by field values (e.g. 'status.phase=Running', 'spec.nodeName=node1'). Supported fields: metadata.name, metadata.namespace, spec.nodeName, spec.restartPolicy, spec.schedulerName, spec.serviceAccountName, status.phase (Pending/Running/Succeeded/Failed/Unknown), status.podIP, status.nominatedNodeName. Note: CrashLoopBackOff is a container state, not a pod phase, so it cannot be filtered directly. See https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
  • labelSelector (string) - Optional Kubernetes label selector (e.g. 'app=myapp,env=prod' or 'app in (myapp,yourapp)'), use this option when you want to filter the pods by label
  • namespace (string) (required) - Namespace to list pods from

• pods_get - Get a Kubernetes Pod in the current or provided namespace with the provided name

  • name (string) (required) - Name of the Pod
  • namespace (string) - Namespace to get the Pod from

• pods_delete - Delete a Kubernetes Pod in the current or provided namespace with the provided name

  • name (string) (required) - Name of the Pod to delete
  • namespace (string) - Namespace to delete the Pod from

• pods_top - List the resource consumption (CPU and memory) as recorded by the Kubernetes Metrics Server for the specified Kubernetes Pods in the all namespaces, the provided namespace, or the current namespace

  • all_namespaces (boolean) - If true, list the resource consumption for all Pods in all namespaces. If false, list the resource consumption for Pods in the provided namespace or the current namespace
  • label_selector (string) - Kubernetes label selector (e.g. 'app=myapp,env=prod' or 'app in (myapp,yourapp)'), use this option when you want to filter the pods by label (Optional, only applicable when name is not provided)
  • name (string) - Name of the Pod to get the resource consumption from (Optional, all Pods in the namespace if not provided)
  • namespace (string) - Namespace to get the Pods resource consumption from (Optional, current namespace if not provided and all_namespaces is false)

• pods_exec - Execute a command in a Kubernetes Pod (shell access, run commands in container) in the current or provided namespace with the provided name and command

  • command (array) (required) - Command to execute in the Pod container. The first item is the command to be run, and the rest are the arguments to that command. Example: ["ls", "-l", "/tmp"]
  • container (string) - Name of the Pod container where the command will be executed (Optional)
  • name (string) (required) - Name of the Pod where the command will be executed
  • namespace (string) - Namespace of the Pod where the command will be executed

• pods_log - Get the logs of a Kubernetes Pod in the current or provided namespace with the provided name

  • container (string) - Name of the Pod container to get the logs from (Optional)
  • name (string) (required) - Name of the Pod to get the logs from
  • namespace (string) - Namespace to get the Pod logs from
  • previous (boolean) - Return previous terminated container logs (Optional)
  • tail (integer) - Number of lines to retrieve from the end of the logs (Optional, default: 100)

• pods_run - Run a Kubernetes Pod in the current or provided namespace with the provided container image and optional name

  • image (string) (required) - Container Image to run in the Pod
  • name (string) - Name of the Pod (Optional, random name if not provided)
  • namespace (string) - Namespace to run the Pod in
  • port (number) - TCP/IP port to expose from the Pod container (Optional, no port exposed if not provided)

• resources_list - List Kubernetes resources and objects in the current cluster by providing their apiVersion and kind and optionally the namespace and label selector (common apiVersion and kind include: v1 Pod, v1 Service, v1 Node, apps/v1 Deployment, networking.k8s.io/v1 Ingress, route.openshift.io/v1 Route)

  • apiVersion (string) (required) - apiVersion of the resources (examples of valid apiVersion are: v1, apps/v1, networking.k8s.io/v1)
  • fieldSelector (string) - Optional Kubernetes field selector to filter resources by field values (e.g. 'status.phase=Running', 'metadata.name=myresource'). Supported fields vary by resource type. For Pods: metadata.name, metadata.namespace, spec.nodeName, spec.restartPolicy, spec.schedulerName, spec.serviceAccountName, status.phase (Pending/Running/Succeeded/Failed/Unknown), status.podIP, status.nominatedNodeName. See https://kubernetes.io/docs/concepts/overview/working-with-objects/field-selectors/
  • kind (string) (required) - kind of the resources (examples of valid kind are: Pod, Service, Deployment, Ingress)
  • labelSelector (string) - Optional Kubernetes label selector (e.g. 'app=myapp,env=prod' or 'app in (myapp,yourapp)'), use this option when you want to filter the resources by label
  • namespace (string) - Optional Namespace to retrieve the namespaced resources from (ignored in case of cluster scoped resources). If not provided, will list resources from all namespaces

• resources_get - Get a Kubernetes resource in the current cluster by providing its apiVersion, kind, optionally the namespace, and its name (common apiVersion and kind include: v1 Pod, v1 Service, v1 Node, apps/v1 Deployment, networking.k8s.io/v1 Ingress, route.openshift.io/v1 Route)

  • apiVersion (string) (required) - apiVersion of the resource (examples of valid apiVersion are: v1, apps/v1, networking.k8s.io/v1)
  • kind (string) (required) - kind of the resource (examples of valid kind are: Pod, Service, Deployment, Ingress)
  • name (string) (required) - Name of the resource
  • namespace (string) - Optional Namespace to retrieve the namespaced resource from (ignored in case of cluster scoped resources). If not provided, will get resource from configured namespace

• resources_create_or_update - Create or update a Kubernetes resource via Server-Side Apply. The manifest is the complete desired state: any field this tool previously set and the new manifest omits is removed. To edit an existing resource, fetch it with resources_get, modify it, then re-apply the full resource. (common apiVersion and kind include: v1 Pod, v1 Service, v1 Node, apps/v1 Deployment, networking.k8s.io/v1 Ingress, route.openshift.io/v1 Route)

  • resource (string) (required) - Complete YAML or JSON representation of the Kubernetes resource (full desired state, not a partial patch). Include apiVersion, kind, metadata, and the full spec.

• resources_delete - Delete a Kubernetes resource in the current cluster by providing its apiVersion, kind, optionally the namespace, and its name (common apiVersion and kind include: v1 Pod, v1 Service, v1 Node, apps/v1 Deployment, networking.k8s.io/v1 Ingress, route.openshift.io/v1 Route)

  • apiVersion (string) (required) - apiVersion of the resource (examples of valid apiVersion are: v1, apps/v1, networking.k8s.io/v1)
  • gracePeriodSeconds (integer) - Optional duration in seconds before the object should be deleted. Value must be non-negative integer. The value zero indicates delete immediately. If this value is nil, the default grace period for the specified type will be used
  • kind (string) (required) - kind of the resource (examples of valid kind are: Pod, Service, Deployment, Ingress)
  • name (string) (required) - Name of the resource
  • namespace (string) - Optional Namespace to delete the namespaced resource from (ignored in case of cluster scoped resources). If not provided, will delete resource from configured namespace

• resources_scale - Get or update the scale of a Kubernetes resource in the current cluster by providing its apiVersion, kind, name, and optionally the namespace. If the scale is set in the tool call, the scale will be updated to that value. Always returns the current scale of the resource

  • apiVersion (string) (required) - apiVersion of the resource (examples of valid apiVersion are apps/v1)
  • kind (string) (required) - kind of the resource (examples of valid kind are: StatefulSet, Deployment)
  • name (string) (required) - Name of the resource
  • namespace (string) - Optional Namespace to get/update the namespaced resource scale from (ignored in case of cluster scoped resources). If not provided, will get/update resource scale from configured namespace
  • scale (integer) - Optional scale to update the resources scale to. If not provided, will return the current scale of the resource, and not update it

helm

• helm_install - Install (deploy) a Helm chart to create a release in the current or provided namespace

  • chart (string) (required) - Chart reference to install (for example: stable/grafana, oci://ghcr.io/nginxinc/charts/nginx-ingress)
  • name (string) - Name of the Helm release (Optional, random name if not provided)
  • namespace (string) - Namespace to install the Helm chart in (Optional, current namespace if not provided)
  • values (object) - Values to pass to the Helm chart (Optional)

• helm_list - List all the Helm releases in the current or provided namespace (or in all namespaces if specified)

  • all_namespaces (boolean) - If true, lists all Helm releases in all namespaces ignoring the namespace argument (Optional)
  • namespace (string) - Namespace to list Helm releases from (Optional, all namespaces if not provided)

• helm_uninstall - Uninstall a Helm release in the current or provided namespace

  • name (string) (required) - Name of the Helm release to uninstall
  • namespace (string) - Namespace to uninstall the Helm release from (Optional, current namespace if not provided)

kcp

• kcp_workspaces_list - List all available kcp workspaces in the current cluster

• kcp_workspace_describe - Get detailed information about a specific kcp workspace

  • workspace (string) (required) - Name or path of the workspace to describe

kubevirt

• vm_clone - Clone a VirtualMachine on KubeVirt by creating a VirtualMachineClone resource. This creates a copy of the source VM with a new name using the KubeVirt Clone API

  • name (string) (required) - The name of the source virtual machine to clone
  • namespace (string) (required) - The namespace of the source virtual machine
  • targetName (string) (required) - The name for the new cloned virtual machine

• vm_create - Create a VirtualMachine on KubeVirt with the specified configuration, automatically resolving instance types, preferences, and container disk images. VM will be created in Halted state by default; use autostart parameter to start it immediately.

  • autostart (boolean) - Optional flag to automatically start the VM after creation (sets runStrategy to Always instead of Halted). Defaults to false.
  • instancetype (string) - Optional instance type name for the VM (e.g., 'u1.small', 'u1.medium', 'u1.large')
  • name (string) (required) - The name of the virtual machine
  • namespace (string) (required) - The namespace for the virtual machine
  • networks (array) - Optional secondary network interfaces to attach to the VM. Each item specifies a Multus NetworkAttachmentDefinition to attach. Accepts either simple strings (NetworkAttachmentDefinition names) or objects with 'name' (interface name in VM) and 'networkName' (NetworkAttachmentDefinition name) properties. Each network creates a bridge interface on the VM.
  • performance (string) - Optional performance family hint for the VM instance type (e.g., 'u1' for general-purpose, 'o1' for overcommitted, 'c1' for compute-optimized, 'm1' for memory-optimized). Defaults to 'u1' (general-purpose) if not specified.
  • preference (string) - Optional preference name for the VM
  • size (string) - Optional workload size hint for the VM (e.g., 'small', 'medium', 'large', 'xlarge'). Used to auto-select an appropriate instance type if not explicitly specified.
  • storage (string) - Optional storage size for the VM's root disk when using DataSources (e.g., '30Gi', '50Gi', '100Gi'). Defaults to 30Gi. Ignored when using container disks.
  • workload (string) - The workload for the VM. Accepts OS names (e.g., 'fedora' (default), 'ubuntu', 'centos', 'centos-stream', 'debian', 'rhel', 'opensuse', 'opensuse-tumbleweed', 'opensuse-leap') or full container disk image URLs

• vm_guest_info - Get guest operating system information from a VirtualMachine's QEMU guest agent. Requires the guest agent to be installed and running inside the VM. Provides detailed information about the OS, filesystems, network interfaces, and logged-in users.

  • info_type (string) - Type of information to retrieve: 'all' (default - all available info), 'os' (operating system details), 'filesystem' (disk and filesystem info), 'users' (logged-in users), 'network' (network interfaces and IPs)
  • name (string) (required) - The name of the virtual machine
  • namespace (string) (required) - The namespace of the virtual machine

• vm_lifecycle - Manage OpenShift Virtualization VirtualMachine lifecycle: start, stop, or restart a VM

  • action (string) (required) - The lifecycle action to perform: 'start' (changes runStrategy to Always), 'stop' (changes runStrategy to Halted), or 'restart' (stops then starts the VM)
  • name (string) (required) - The name of the virtual machine
  • namespace (string) (required) - The namespace of the virtual machine

netobserv

• netobserv_list_flows - Lists NetObserv network flow records from Loki. Use when investigating traffic between workloads, IPs, ports, or protocols in a namespace or time window.
  • endTime (integer) - End of time range as Unix epoch seconds. Defaults to now.
  • filters (string) - NetObserv filter expression passed to the console plugin (plain text; the client URL-encodes it).

Syntax:

• key=value — exact match; key=a,b — OR multiple values for the same key
• key~pattern — regex / contains match; key!~pattern — NOT regex
• key!=value — not equal; key>number — numeric greater-or-equal (e.g. Bytes>1000)
• AND within a group: & (e.g. SrcK8S_Namespace=default&Proto=6)
• OR between groups: | (e.g. SrcK8S_Name=pod-a|SrcK8S_Name=pod-b)

Prefer the dedicated "namespace" parameter for namespace scope when possible. Use Kubernetes list tools (namespaces, pods, deployments, etc.) to discover filter values.

Common Kubernetes fields (Src/Dst prefixes mirror each other):

• SrcK8S_Namespace, DstK8S_Namespace, SrcK8S_Name, DstK8S_Name
• SrcK8S_Type, DstK8S_Type (e.g. Pod, Service, Node)
• SrcK8S_OwnerName, DstK8S_OwnerName, SrcK8S_OwnerType, DstK8S_OwnerType (for Deployment, StatefulSet, etc.)
• SrcK8S_HostName, DstK8S_HostName, SrcK8S_Zone, DstK8S_Zone, K8S_ClusterName, UDN

Network & flow:

• SrcAddr, DstAddr (IPs), SrcPort, DstPort, Proto (IANA number, e.g. 6=TCP, 17=UDP)
• FlowDirection (0=Ingress, 1=Egress, 2=Inner), Bytes, Packets, Dscp, Flags

Packet drops (often with recordType flowLog and packetLoss dropped/hasDrops):

• PktDropPackets, PktDropBytes, PktDropLatestState, PktDropLatestDropCause

DNS:

• DnsName, DnsId, DnsLatencyMs, DnsErrno, DnsFlagsResponseCode

Examples:

• SrcK8S_Namespace=openshift-netobserv&SrcK8S_Name~my-app

• Proto=6&DstPort=443

• SrcK8S_Name=pod-a|SrcK8S_Name=pod-b

  • limit (integer) - Maximum number of flow records to return. Default 100.
  • namespace (string) - Restrict results to flows where source or destination namespace matches (dev-scoped Loki tenant).
  • packetLoss (string) - Packet loss filter.
  • recordType (string) - Flow record type filter.
  • startTime (integer) - Start of time range as Unix epoch seconds. Overrides timeRange when set.
  • timeRange (integer) - Lookback window in seconds when startTime is omitted. Default 300.

• netobserv_get_flow_metrics - Returns aggregated NetObserv flow metrics as topology or time-series data. Use for throughput, TLS/DNS/drop breakdowns, and namespace or workload traffic analysis; see aggregateBy and groups for grouping options.

  • aggregateBy (string) (required) - Primary dimension for netobserv_get_flow_metrics (console plugin /api/flow/metrics).

Two forms (use exact spelling):

1. Topology scopes — aggregate endpoints for graph/topology views:

• app — application workloads (pods/services), excluding infrastructure traffic
• namespace — Kubernetes namespace (default)
• owner — controller owner (Deployment, StatefulSet, …)
• resource — pod, service, or node (finest workload granularity)
• host — node name
• zone — availability zone
• cluster — cluster name (multi-cluster)
• network — user-defined / secondary network name

2. Flow record fields — group by a single flow attribute (PascalCase field name). Use for breakdown charts (TLS, DNS, drops, protocol). Field names match filters / flow logs.

TLS (requires TLS tracking on the FlowCollector):

• TLSVersion, TLSCipherSuite, TLSGroup, TLSTypes

DNS:

• DnsName, DnsFlagsResponseCode, DnsErrno

Packet drops:

• PktDropLatestState, PktDropLatestDropCause

Network / K8s (single-sided breakdown; pair with filters for src/dst):

• Proto, SrcPort, DstPort, FlowDirection, Dscp
• SrcK8S_Namespace, DstK8S_Namespace, SrcK8S_Name, DstK8S_Name
• SrcK8S_Type, DstK8S_Type, SrcK8S_OwnerName, DstK8S_OwnerName
• SrcK8S_HostName, DstK8S_HostName, SrcK8S_Zone, DstK8S_Zone
• K8S_ClusterName, SrcK8S_NetworkName, DstK8S_NetworkName

Pair aggregateBy with type and function:

• Throughput: type=Bytes or Packets, function=rate
• Flow count: type=Flows, function=count or rate
• DNS volume: type=DnsFlows, function=count
• DNS latency: type=DnsLatencyMs, function=avg, p90, or max
• RTT: type=TimeFlowRttNs, function=avg, min, or p90
• Drops: type=PktDropPackets or PktDropBytes, function=rate

Examples:

• aggregateBy=namespace, type=Bytes, function=rate
• aggregateBy=TLSVersion, type=Bytes, function=rate, filters=TLSTypes!~""
• aggregateBy=TLSGroup, type=Flows, function=count
• aggregateBy=DnsFlagsResponseCode, type=DnsFlows, function=count
• aggregateBy=PktDropLatestState, type=PktDropPackets, function=rate, packetLoss=dropped
• aggregateBy=resource, type=Bytes, function=rate, namespace=netobserv
  • dataSource (string) - Metrics backend: auto (prefer Prometheus, fallback to Loki), prom, or loki.
  • endTime (integer) - End of time range as Unix epoch seconds. Defaults to now.
  • filters (string) - NetObserv filter expression passed to the console plugin (plain text; the client URL-encodes it).

Syntax:

• key=value — exact match; key=a,b — OR multiple values for the same key
• key~pattern — regex / contains match; key!~pattern — NOT regex
• key!=value — not equal; key>number — numeric greater-or-equal (e.g. Bytes>1000)
• AND within a group: & (e.g. SrcK8S_Namespace=default&Proto=6)
• OR between groups: | (e.g. SrcK8S_Name=pod-a|SrcK8S_Name=pod-b)

Prefer the dedicated "namespace" parameter for namespace scope when possible. Use Kubernetes list tools (namespaces, pods, deployments, etc.) to discover filter values.

Common Kubernetes fields (Src/Dst prefixes mirror each other):

• SrcK8S_Namespace, DstK8S_Namespace, SrcK8S_Name, DstK8S_Name
• SrcK8S_Type, DstK8S_Type (e.g. Pod, Service, Node)
• SrcK8S_OwnerName, DstK8S_OwnerName, SrcK8S_OwnerType, DstK8S_OwnerType (for Deployment, StatefulSet, etc.)
• SrcK8S_HostName, DstK8S_HostName, SrcK8S_Zone, DstK8S_Zone, K8S_ClusterName, UDN

Network & flow:

• SrcAddr, DstAddr (IPs), SrcPort, DstPort, Proto (IANA number, e.g. 6=TCP, 17=UDP)
• FlowDirection (0=Ingress, 1=Egress, 2=Inner), Bytes, Packets, Dscp, Flags

Packet drops (often with recordType flowLog and packetLoss dropped/hasDrops):

• PktDropPackets, PktDropBytes, PktDropLatestState, PktDropLatestDropCause

DNS:

• DnsName, DnsId, DnsLatencyMs, DnsErrno, DnsFlagsResponseCode

Examples:

• SrcK8S_Namespace=openshift-netobserv&SrcK8S_Name~my-app
• Proto=6&DstPort=443
• SrcK8S_Name=pod-a|SrcK8S_Name=pod-b
  • function (string) - Aggregation function.
  • groups (string) - Optional comma-separated parent scopes when aggregateBy is a topology scope. Adds extra label dimensions (e.g. break namespace results down by cluster or zone). Ignored or less useful when aggregateBy is already a raw flow field (e.g. TLSVersion); use filters instead.

Single scopes:

• clusters, networks, zones, hosts, namespaces, owners

Combined scopes (use +, no spaces):

• clusters+zones, clusters+hosts, clusters+namespaces, clusters+owners
• zones+hosts, zones+namespaces, zones+owners
• hosts+namespaces, hosts+owners
• namespaces+owners
• networks+zones, networks+hosts, networks+namespaces, networks+owners

Examples:

• aggregateBy=namespace, groups=clusters

• aggregateBy=resource, groups=namespaces

• aggregateBy=owner, groups=zones,hosts

  • limit (integer) - Maximum number of flow records to return. Default 100.
  • namespace (string) - Restrict results to flows where source or destination namespace matches (dev-scoped Loki tenant).
  • packetLoss (string) - Packet loss filter.
  • rateInterval (string) - Prometheus rate interval (e.g. 1m, 5m).
  • recordType (string) - Flow record type filter.
  • startTime (integer) - Start of time range as Unix epoch seconds. Overrides timeRange when set.
  • step (string) - Query resolution step (e.g. 30s, 1m).
  • timeRange (integer) - Lookback window in seconds when startTime is omitted. Default 300.
  • type (string) - Metric type to aggregate.

• netobserv_export_flows - Exports NetObserv flow records as CSV with the same filters as list_flows. Use when the user needs downloadable flow data for audits or offline analysis.

  • columns (string) - Optional comma-separated column names to include (e.g. SrcK8S_Namespace,DstK8S_Namespace,Bytes). Omit to export all columns present in the result.
  • endTime (integer) - End of time range as Unix epoch seconds. Defaults to now.
  • filters (string) - NetObserv filter expression passed to the console plugin (plain text; the client URL-encodes it).

Syntax:

• key=value — exact match; key=a,b — OR multiple values for the same key
• key~pattern — regex / contains match; key!~pattern — NOT regex
• key!=value — not equal; key>number — numeric greater-or-equal (e.g. Bytes>1000)
• AND within a group: & (e.g. SrcK8S_Namespace=default&Proto=6)
• OR between groups: | (e.g. SrcK8S_Name=pod-a|SrcK8S_Name=pod-b)

Prefer the dedicated "namespace" parameter for namespace scope when possible. Use Kubernetes list tools (namespaces, pods, deployments, etc.) to discover filter values.

Common Kubernetes fields (Src/Dst prefixes mirror each other):

• SrcK8S_Namespace, DstK8S_Namespace, SrcK8S_Name, DstK8S_Name
• SrcK8S_Type, DstK8S_Type (e.g. Pod, Service, Node)
• SrcK8S_OwnerName, DstK8S_OwnerName, SrcK8S_OwnerType, DstK8S_OwnerType (for Deployment, StatefulSet, etc.)
• SrcK8S_HostName, DstK8S_HostName, SrcK8S_Zone, DstK8S_Zone, K8S_ClusterName, UDN

Network & flow:

• SrcAddr, DstAddr (IPs), SrcPort, DstPort, Proto (IANA number, e.g. 6=TCP, 17=UDP)
• FlowDirection (0=Ingress, 1=Egress, 2=Inner), Bytes, Packets, Dscp, Flags

Packet drops (often with recordType flowLog and packetLoss dropped/hasDrops):

• PktDropPackets, PktDropBytes, PktDropLatestState, PktDropLatestDropCause

DNS:

• DnsName, DnsId, DnsLatencyMs, DnsErrno, DnsFlagsResponseCode

Examples:

• SrcK8S_Namespace=openshift-netobserv&SrcK8S_Name~my-app
• Proto=6&DstPort=443
• SrcK8S_Name=pod-a|SrcK8S_Name=pod-b
  • format (string) - Export format. Only csv is supported.
  • limit (integer) - Maximum number of flow records to return. Default 100.
  • namespace (string) - Restrict results to flows where source or destination namespace matches (dev-scoped Loki tenant).
  • packetLoss (string) - Packet loss filter.
  • recordType (string) - Flow record type filter.
  • startTime (integer) - Start of time range as Unix epoch seconds. Overrides timeRange when set.
  • timeRange (integer) - Lookback window in seconds when startTime is omitted. Default 300.

tekton

• tekton_pipeline_start - Start a Tekton Pipeline by creating a PipelineRun that references it

  • name (string) (required) - Name of the Pipeline to start
  • namespace (string) - Namespace of the Pipeline
  • params (object) - Parameter values to pass to the Pipeline. Keys are parameter names; values can be a string, an array of strings, or an object (map of string to string) depending on the parameter type defined in the Pipeline spec

• tekton_pipelinerun_restart - Restart a Tekton PipelineRun by creating a new PipelineRun with the same spec

  • name (string) (required) - Name of the PipelineRun to restart
  • namespace (string) - Namespace of the PipelineRun

• tekton_task_start - Start a Tekton Task by creating a TaskRun that references it

  • name (string) (required) - Name of the Task to start
  • namespace (string) - Namespace of the Task
  • params (object) - Parameter values to pass to the Task. Keys are parameter names; values can be a string, an array of strings, or an object (map of string to string) depending on the parameter type defined in the Task spec

• tekton_taskrun_restart - Restart a Tekton TaskRun by creating a new TaskRun with the same spec

  • name (string) (required) - Name of the TaskRun to restart
  • namespace (string) - Namespace of the TaskRun

• tekton_taskrun_logs - Get the logs from a Tekton TaskRun by resolving its underlying pod

  • name (string) (required) - Name of the TaskRun to get logs from
  • namespace (string) - Namespace of the TaskRun
  • tail (integer) - Number of lines to retrieve from the end of the logs (Optional, default: 100)

Prompts

core

• cluster-health-check - Perform comprehensive health assessment of Kubernetes/OpenShift cluster
  • namespace (string) - Optional namespace to limit health check scope (default: all namespaces)
  • check_events (string) - Include recent warning/error events (true/false, default: true)

kubevirt

• vm-troubleshoot - Generate a step-by-step troubleshooting guide for diagnosing OpenShift Virtualization VirtualMachine issues

  • namespace (string) (required) - The namespace of the VirtualMachine to troubleshoot
  • name (string) (required) - The name of the VirtualMachine to troubleshoot

• windows-golden-image - Guides creation of a Windows golden image via the OpenShift Virtualization windows-efi-installer Tekton pipeline

  • winImageDownloadURL (string) (required) - Microsoft Windows ISO download URL (must be https://)
  • namespace (string) - Target namespace for the PipelineRun
  • windowsVersion (string) - Windows version: 10, 11, 2k22 (default), or 2k25
  • pipelineVersion (string) - Pipeline version (default: latest). Use specific version like 0.25.0 if needed

oadp

• oadp-troubleshoot - Generate a step-by-step troubleshooting guide for diagnosing OADP backup and restore issues
  • namespace (string) - The OADP namespace (default: openshift-adp)
  • backup (string) - The name of a specific backup to troubleshoot
  • restore (string) - The name of a specific restore to troubleshoot

openshift

• plan_mustgather - Plan for collecting a must-gather archive from an OpenShift cluster. Must-gather is a tool for collecting cluster data related to debugging and troubleshooting like logs, kubernetes resources, etc.
  • node_name (string) - Specific node name to run must-gather pod on
  • node_selector (string) - Node selector in key=value,key2=value2 format to filter nodes for the pod
  • source_dir (string) - Custom gather directory inside pod (default: /must-gather)
  • namespace (string) - Privileged namespace to use for must-gather (auto-generated if not specified)
  • gather_command (string) - Custom gather command eg. /usr/bin/gather_audit_logs (default: /usr/bin/gather)
  • timeout (string) - Timeout duration for gather command (eg. 30m, 1h)
  • since (string) - Only gather data newer than this duration (eg. 5s, 2m5s, or 3h6m10s) defaults to all data.
  • host_network (string) - Use host network for must-gather pod (true/false)
  • keep_resources (string) - Keep pod resources after collection (true/false, default: false)
  • all_component_images (string) - Include must-gather images from all installed operators (true/false)
  • images (string) - Comma-separated list of custom must-gather container images

ossm

• mesh-list-applications - List applications in the mesh namespaces

  • namespace (string) - Optional namespace to filter applications (default: all namespaces)

• list-istio-config - List Istio configuration resources in the mesh namespaces

  • namespace (string) - Optional namespace to filter Istio configuration (default: all namespaces)

• mesh-list-namespaces - List all namespaces with their sidecar injection status and Istio labels

• mesh-list-services - List services in the mesh namespaces

  • namespace (string) - Optional namespace to filter services (default: all namespaces)

• mesh-list-workloads - List workloads in the mesh namespaces

  • namespace (string) - Optional namespace to filter workloads (default: all namespaces)

• mesh-health-check - Perform a comprehensive health assessment of the Istio service mesh including control plane and data plane status

  • namespace (string) - Optional namespace to focus the health check on (default: all namespaces)

• mesh-topology - Show the mesh topology including control plane components and cluster connectivity

• traffic-topology - Analyze the service mesh traffic topology showing service dependencies, traffic flow, and communication patterns

  • namespaces (string) (required) - Comma-separated list of namespaces to include in the graph, or 'all' to include all accessible mesh namespaces

• service-troubleshoot - Investigate service errors using logs, traces, and Istio configuration to identify root causes

  • namespace (string) (required) - Namespace where the service is deployed
  • service (string) (required) - Name of the service to troubleshoot
  • workload (string) - Optional workload or pod name to fetch logs from (if omitted, uses the service name)

• trace-analysis - Investigate distributed traces for a service to identify latency bottlenecks, error sources, and slow spans

  • namespace (string) (required) - Namespace where the service is deployed
  • service (string) (required) - Name of the service to investigate traces for

• istio-config-review - Review and validate Istio configuration in a namespace, checking for misconfigurations and best practice violations

  • namespace (string) (required) - Namespace to review Istio configuration for

Resources

Resource Templates

Helm Chart

A Helm Chart is available to simplify the deployment of the Kubernetes MCP server.

helm install kubernetes-mcp-server oci://ghcr.io/containers/charts/kubernetes-mcp-server

For configuration options including OAuth, telemetry, and resource limits, see the chart README and values.yaml.

💬 Community

Join the conversation and connect with other users and contributors:

• Slack - Ask questions, share feedback, and discuss the Kubernetes MCP server in the #kubernetes-mcp-server channel on the CNCF Slack workspace. If you're not already a member, you can request an invitation.

🧑‍💻 Development

Running with mcp-inspector

Compile the project and run the Kubernetes MCP server with mcp-inspector to inspect the MCP server.

# Compile the project
make build
# Run the Kubernetes MCP server with mcp-inspector
npx @modelcontextprotocol/inspector@latest $(pwd)/kubernetes-mcp-server

---

mcp-name: io.github.containers/kubernetes-mcp-server