Kubernetes

Kubernetes MCP Server

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

https://github.com/user-attachments/assets/be2b67b3-fc1c-4d11-ae46-93deba8ed98e

✨ 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, cancel, troubleshoot, and retrieve PipelineRun logs.
  • 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.

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.

https://github.com/user-attachments/assets/a576176d-a142-4c19-b9aa-a83dc4b8d941

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

Note: Runtime settings are TOML (or existing env names), not CLI flags. See Configuration Changes for the flag-to-TOML mapping.

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 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.

Available Toolsets

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

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.

• 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)

• events_list - List Kubernetes events (warnings, errors, state changes) for debugging and troubleshooting in the current cluster from all namespaces. Use limit and continue to retrieve a large list one page at a time.

  • continue (string) - Opaque token from the continue field of the previous page. Send it unchanged with the same limit, namespace, and selectors to retrieve the next page. Omit on the first call.
  • 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/
  • limit (integer) - Maximum number of items to return. Omit or set to 0 to list everything, which fails if the response exceeds max_backend_response_bytes. Retry with a smaller limit when that happens. The API may return fewer items than requested.
  • 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. Use limit and continue to retrieve a large list one page at a time.

  • continue (string) - Opaque token from the continue field of the previous page. Send it unchanged with the same limit, namespace, and selectors to retrieve the next page. Omit on the first call.
  • 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/
  • limit (integer) - Maximum number of items to return. Omit or set to 0 to list everything, which fails if the response exceeds max_backend_response_bytes. Retry with a smaller limit when that happens. The API may return fewer items than requested.

• projects_list - List all the OpenShift projects in the current cluster. Use limit and continue to retrieve a large list one page at a time.

• 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). Use limit and offset to page the releases returned to you. Helm loads release secrets before applying that page, so a secret list that exceeds max_backend_response_bytes can still fail.

  • all_namespaces (boolean) - If true, lists all Helm releases in all namespaces ignoring the namespace argument (Optional)
  • limit (integer) - Maximum number of releases to return. Omit or set to 0 to return every release Helm loaded. A full page tells you the next offset.
  • namespace (string) - Namespace to list Helm releases from (Optional, all namespaces if not provided)
  • offset (integer) - Number of releases to skip. Send the next offset from a full page, with the same limit.

• 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_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

• kiali_get_mesh_traffic_graph - Returns service-to-service traffic topology, dependencies, and network metrics (throughput, response time, mTLS) for the specified namespaces. Use this to diagnose routing issues, latency, or find upstream/downstream dependencies.

  • graphType (string) - Granularity of the graph. 'app' aggregates by app name, 'versionedApp' separates by versions, 'workload' maps specific pods/deployments. Default: versionedApp.
  • meshCluster (string) - Optional Istio mesh cluster name from kiali_list_mesh_clusters (e.g. west). When omitted, Kiali defaults to its home cluster.
  • namespaces (string) (required) - Comma-separated list of namespaces to map

• kiali_get_mesh_status - Retrieves the high-level health, topology, and environment details of the Istio service mesh. Returns multi-cluster control plane status (istiod), data plane namespace health (including ambient mesh status), observability stack health (Prometheus, Grafana...), and component connectivity. Use this tool as the first step to diagnose mesh-wide issues, verify Istio/Kiali versions, or check overall health before drilling into specific workloads.

• kiali_manage_istio_config_read - Read Istio, Gateway API, and Inference API config. 'list' groups by namespace→'group/version/kind'→{valid:[...],invalid:[...]} where valid/invalid arrays contain resource names; omit group/kind to retrieve ALL config types in a single call. Supports Istio (networking.istio.io, security.istio.io), Gateway API (gateway.networking.k8s.io), and Inference API (inference.networking.k8s.io) when installed. 'get' returns full YAML. For writes use manage_istio_config.

  • action (string) (required) - Action to perform (read-only)
  • group (string) - API group of the Istio object. Required ONLY for 'get' action. For 'list', OMIT group and kind to retrieve ALL config types in a single call. Use 'gateway.networking.k8s.io' for Gateway API resources. Use 'inference.networking.k8s.io' for Inference API resources.
  • kind (string) - Kind of the Istio object. Required ONLY for 'get' action. For 'list', OMIT to return all kinds at once — do NOT call separately for each kind.
  • meshCluster (string) - Optional Istio mesh cluster name from kiali_list_mesh_clusters (e.g. west). When omitted, Kiali defaults to its home cluster.
  • namespace (string) - Namespace containing the Istio object. For 'list', if not provided, returns objects across all namespaces. For 'get', required.

• 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_console_screenshot - Capture a screenshot of the graphical (VNC) console of a VirtualMachine on KubeVirt as a PNG image. Use this to see what is currently displayed on the VM's screen (for example firmware, a bootloader, or a login prompt). Read-only: it never sends input to the guest.

  • name (string) (required) - The name of the virtual machine
  • namespace (string) (required) - The namespace of the 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.

• 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_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.

• 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.

• loki_list_instances - List LokiStack instances available in the Kubernetes cluster. Call this first when using Loki Operator managed stacks so you can pass lokiNamespace and lokiName to other Loki tools.

• loki_label_names - List available Loki label names for a time range. Use this before writing LogQL queries.

  • end (string) - End time as RFC3339, Unix timestamp, NOW, or NOW-relative expression (optional).
  • lokiName (string) - Name of the LokiStack. Use loki_list_instances to discover valid values.
  • lokiNamespace (string) - Kubernetes namespace of the LokiStack. Use loki_list_instances to discover valid values.
  • start (string) - Start time as RFC3339, Unix timestamp, NOW, or NOW-relative expression (optional).
  • tenant (string) - Loki tenant ID (X-Scope-OrgID). For LokiStack gateway modes (e.g. openshift-network) this selects the /api/logs/v1/<tenant> path; use network for openshift-network.

• loki_label_values - List possible values for a Loki label key. Use this to build precise label matchers in LogQL.

  • end (string) - End time as RFC3339, Unix timestamp, NOW, or NOW-relative expression (optional).
  • label (string) (required) - Label key to inspect (for example namespace, pod, container).
  • lokiName (string) - Name of the LokiStack. Use loki_list_instances to discover valid values.
  • lokiNamespace (string) - Kubernetes namespace of the LokiStack. Use loki_list_instances to discover valid values.
  • start (string) - Start time as RFC3339, Unix timestamp, NOW, or NOW-relative expression (optional).
  • tenant (string) - Loki tenant ID (X-Scope-OrgID). For LokiStack gateway modes (e.g. openshift-network) this selects the /api/logs/v1/<tenant> path; use network for openshift-network.

• loki_query_range - Execute a Loki LogQL range query and return matching log streams and lines.

Use precise label matchers and a short time window first.

• direction (string) - Search direction: backward (default) or forward.
• duration (string) - Lookback duration from now when start/end are omitted (for example 5m, 1h). Defaults to 15m.
• end (string) - End time as RFC3339, Unix timestamp, NOW, or NOW-relative expression (optional).
• limit (integer) - Maximum number of log lines to return. Defaults to 100, max 1000.
• lokiName (string) - Name of the LokiStack. Use loki_list_instances to discover valid values.
• lokiNamespace (string) - Kubernetes namespace of the LokiStack. Use loki_list_instances to discover valid values.
• query (string) (required) - LogQL query string.
• start (string) - Start time as RFC3339, Unix timestamp, NOW, or NOW-relative expression (optional).
• tenant (string) - Loki tenant ID (X-Scope-OrgID). For LokiStack gateway modes (e.g. openshift-network) this selects the /api/logs/v1/<tenant> path; use network for openshift-network.

• list_metrics - MANDATORY FIRST STEP: List all available metric names in Prometheus.

YOU MUST CALL THIS TOOL BEFORE ANY OTHER QUERY TOOL

This tool MUST be called first for EVERY observability question to:

1. Discover what metrics actually exist in this environment
2. Find the EXACT metric name to use in queries
3. Avoid querying non-existent metrics
4. The 'name_regex' parameter should always be provided, and be a best guess of what the metric would be named like.
5. Do not use a blanket regex like .* or .+ in the 'name_regex' parameter. Use specific ones like kube., node., etc.

REGEX PATTERN GUIDANCE:

• Prometheus metrics are typically prefixed (e.g., 'prometheus_tsdb_head_series', 'kube_pod_status_phase')
• To match metrics CONTAINING a substring, use wildcards: '.tsdb.' matches 'prometheus_tsdb_head_series'
• Without wildcards, the pattern matches EXACTLY: 'tsdb' only matches a metric literally named 'tsdb' (which rarely exists)
• Common patterns: 'kube_pod.' (pods), '.memory.' (memory-related), 'node_.' (node metrics)
• If you get empty results, try adding '.*' before/after your search term

NEVER skip this step. NEVER guess metric names. Metric names vary between environments.

After calling this tool:

1. Search the returned list for relevant metrics
2. Use the EXACT metric name found in subsequent queries
3. If no relevant metric exists, inform the user

• name_regex (string) (required) - Regex pattern to filter metric names. IMPORTANT: Metric names are typically prefixed (e.g., 'prometheus_tsdb_head_series'). Use wildcards to match substrings: '.tsdb.' matches any metric containing 'tsdb', while 'tsdb' only matches the exact string 'tsdb'. Examples: 'http_.' (starts with http_), '.memory.' (contains memory), 'node_.' (starts with node_). This parameter is required. Don't pass in blanket regex like '.*' or '.+'.

• execute_instant_query - Execute a PromQL instant query to get current/point-in-time values.

PREREQUISITE: You MUST call list_metrics first to verify the metric exists

WHEN TO USE:

• Current state questions: "What is the current error rate?"
• Point-in-time snapshots: "How many pods are running?"
• Latest values: "Which pods are in Pending state?"

The 'query' parameter MUST use metric names that were returned by list_metrics.

• query (string) (required) - PromQL query string using metric names verified via list_metrics

• time (string) - Evaluation time as RFC3339 or Unix timestamp. Omit or use 'NOW' for current time.

• execute_range_query - Execute a PromQL range query to get time-series data over a period.

PREREQUISITE: You MUST call list_metrics first to verify the metric exists

WHEN TO USE:

• Trends over time: "What was CPU usage over the last hour?"
• Rate calculations: "How many requests per second?"
• Historical analysis: "Were there any restarts in the last 5 minutes?"

TIME PARAMETERS:

• 'duration': Look back from now (e.g., "5m", "1h", "24h")
• 'step': Data point resolution (e.g., "1m" for 1-hour duration, "5m" for 24-hour duration)

The 'query' parameter MUST use metric names that were returned by list_metrics.

• duration (string) - Duration to look back from now (e.g., '1h', '30m', '1d', '2w') (optional)

• end (string) - End time as RFC3339 or Unix timestamp (optional). Use NOW for current time.

• query (string) (required) - PromQL query string using metric names verified via list_metrics

• start (string) - Start time as RFC3339 or Unix timestamp (optional)

• step (string) (required) - Query resolution step width (e.g., '15s', '1m', '1h'). Choose based on time range: shorter ranges use smaller steps.

• show_timeseries - Display the results as an interactive timeseries chart.

This tool works like execute_range_query but renders the results as a visual chart in the UI clients. Use it when the user wants to see a graph or visualization of time-series data and to use visuals to provide the answer. Use the show_timeseries as the last tool call after all the other Prometheus tool calls where finalized.

TIME PARAMETERS:

• 'duration': Look back from now (e.g., "5m", "1h", "24h")
• 'step': Data point resolution (e.g., "1m" for 1-hour duration, "5m" for 24-hour duration)
• 'title': A descriptive chart title (e.g., "API Error Rate Over Last Hour")
• 'description': An explanation of the chart's meaning or context (e.g., "Shows the rate of HTTP 5xx errors per second, broken down by pod")

The 'query' parameter MUST be a range query and must use metric names that were returned by list_metrics.

• description (string) - Explanation of the chart's meaning or context (e.g., 'Shows the rate of HTTP 5xx errors per second, broken down by pod'). Displayed below the title when provided.

• duration (string) - Duration to look back from now (e.g., '1h', '30m', '1d', '2w') (optional)

• end (string) - End time as RFC3339 or Unix timestamp (optional). Use NOW for current time.

• query (string) (required) - PromQL query string using metric names verified via list_metrics

• start (string) - Start time as RFC3339 or Unix timestamp (optional)

• step (string) (required) - Query resolution step width (e.g., '15s', '1m', '1h'). Choose based on time range: shorter ranges use smaller steps.

• title (string) - Human-readable chart title describing what the query shows (e.g., 'API Error Rate Over Last Hour'). Displayed above the chart when provided.

• get_label_names - Get all label names (dimensions) available for filtering a metric.

WHEN TO USE (after calling list_metrics):

• To discover how to filter metrics (by namespace, pod, service, etc.)
• Before constructing label matchers in PromQL queries

The 'metric' parameter should use a metric name from list_metrics output.

• end (string) - End time for label discovery as RFC3339 or Unix timestamp (optional, defaults to now)

• metric (string) - Metric name (from list_metrics) to get label names for. Leave empty for all metrics.

• start (string) - Start time for label discovery as RFC3339 or Unix timestamp (optional, defaults to 1 hour ago)

• get_label_values - Get all unique values for a specific label.

WHEN TO USE (after calling list_metrics and get_label_names):

• To find exact label values for filtering (namespace names, pod names, etc.)
• To see what values exist before constructing queries

The 'metric' parameter should use a metric name from list_metrics output.

• end (string) - End time for label value discovery as RFC3339 or Unix timestamp (optional, defaults to now)

• label (string) (required) - Label name (from get_label_names) to get values for

• metric (string) - Metric name (from list_metrics) to scope the label values to. Leave empty for all metrics.

• start (string) - Start time for label value discovery as RFC3339 or Unix timestamp (optional, defaults to 1 hour ago)

• get_series - Get time series matching selectors and preview cardinality.

WHEN TO USE (optional, after calling list_metrics):

• To verify label filters match expected series before querying
• To check cardinality and avoid slow queries

CARDINALITY GUIDANCE:

• <100 series: Safe
• 100-1000: Usually fine

• 1000: Add more label filters

The selector should use metric names from list_metrics output.

• end (string) - End time for series discovery as RFC3339 or Unix timestamp (optional, defaults to now)

• matches (string) (required) - PromQL series selector using metric names from list_metrics

• start (string) - Start time for series discovery as RFC3339 or Unix timestamp (optional, defaults to 1 hour ago)

• get_alerts - Get alerts from Alertmanager.

WHEN TO USE:

• START HERE when investigating issues: if the user asks about things breaking, errors, failures, outages, services being down, or anything going wrong in the cluster
• When the user mentions a specific alert name - use this tool to get the alert's full labels (namespace, pod, service, etc.) which are essential for further investigation with other tools
• To see currently firing alerts in the cluster
• To check which alerts are active, silenced, or inhibited
• To understand what's happening before diving into metrics or logs

INVESTIGATION TIP: Alert labels often contain the exact identifiers (pod names, namespaces, job names) needed for targeted queries with prometheus tools.

FILTERING:

• Use 'active' to filter for only active alerts (not resolved)
• Use 'silenced' to filter for silenced alerts
• Use 'inhibited' to filter for inhibited alerts
• Use 'filter' to apply label matchers (e.g., "alertname=HighCPU")
• Use 'receiver' to filter alerts by receiver name

All filter parameters are optional. Without filters, all alerts are returned.

• active (boolean) - Filter for active alerts only (true/false, optional)

• filter (string) - Label matchers to filter alerts (e.g., 'alertname=HighCPU', optional)

• inhibited (boolean) - Filter for inhibited alerts only (true/false, optional)

• receiver (string) - Receiver name to filter alerts (optional)

• silenced (boolean) - Filter for silenced alerts only (true/false, optional)

• unprocessed (boolean) - Filter for unprocessed alerts only (true/false, optional)

• get_silences - Get silences from Alertmanager.

WHEN TO USE:

• To see which alerts are currently silenced
• To check active, pending, or expired silences
• To investigate why certain alerts are not firing notifications

FILTERING:

• Use 'filter' to apply label matchers to find specific silences

Silences are used to temporarily mute alerts based on label matchers. This tool helps you understand what is currently silenced in your environment.

• filter (string) - Label matchers to filter silences (e.g., 'alertname=HighCPU', optional)

• otelcol_list_components - List available OpenTelemetry Collector components (receivers, processors, exporters, extensions, connectors) for a given version.

  • version (string) - Collector version (e.g., 'v0.100.0'). Defaults to latest available.

• otelcol_get_component_schema - Get the JSON schema for an OpenTelemetry Collector component's configuration options.

  • component_name (string) (required) - Component name from otelcol_list_components (e.g., 'otlp', 'batch', 'debug')
  • component_type (string) (required) - Component type: receiver, processor, exporter, extension, connector
  • version (string) - Collector version (e.g., 'v0.100.0'). Defaults to latest available.

• otelcol_validate_config - Validate an OpenTelemetry Collector component configuration against its JSON schema.

  • component_name (string) (required) - Component name from otelcol_list_components (e.g., 'otlp', 'batch', 'debug')
  • component_type (string) (required) - Component type: receiver, processor, exporter, extension, connector
  • config (string) (required) - Configuration to validate as YAML or JSON string
  • format (string) - Config format: 'yaml' (default) or 'json'
  • version (string) - Collector version (e.g., 'v0.100.0'). Defaults to latest available.

• otelcol_get_versions - List available OpenTelemetry Collector versions and identify the latest.

• tempo_list_instances - List all Tempo instances available in the Kubernetes cluster. Call this tool first to discover available Tempo instances before using other Tempo tools, as the returned namespace, name, and tenant values are required parameters for all other Tempo tools. Always print the output of this tool in a table.

• tempo_get_trace_by_id - Retrieve a single distributed trace by its trace ID from Tempo. Returns the full trace with all its spans, including service names, operation names, durations, and attributes. Use this tool wh