Kubernetes MCP Server

https://github.com/containers/kubernetes-mcp-server
Admin
A Go-based native implementation of a Model Context Protocol (MCP) server for Kubernetes and...
Tokens:284,510
Snippets:1,806
Trust Score:9.6
License:Apache-2.0
Update:4 days ago
Show doc for...
Tokens:
Raw
### Manual steps for NetObserv evals

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/netobserv/README.md

Manual setup and run flow for debugging: create cluster, deploy mock, start server with netobserv toolset, run evals, and clean up.

```bash
make minikube-create-cluster
make setup-netobserv          # deploy mock + port-forward :9001
make run-server TOOLSETS=core,netobserv MCP_CONFIG_DIR=dev/config/mcp-configs
make run-evals EVAL_LABEL_SELECTOR=suite=netobserv
make stop-server stop-netobserv teardown-netobserv
```

--------------------------------

### One-command reproducer for obs evals

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/obs/README.md

Installs Prometheus, Tempo, and Loki stacks, port-forwards backends, starts the MCP server, runs evals, and cleans up. Requires a running cluster (or use `make minikube-create-cluster`), and sets MODEL_BASE_URL/MODEL_KEY for the judge; JUDGE_* variables are optional and default to MODEL_* when unset.

```bash
make minikube-create-cluster   # skip if you already have a cluster
export KUBECONFIG="$PWD/_output/kubeconfig"
export MODEL_BASE_URL='https://your-api-endpoint/v1'
export MODEL_KEY='your-api-key'
# Optional: separate judge endpoint (defaults to MODEL_* when unset)
export JUDGE_BASE_URL='https://your-judge-endpoint/v1'
export JUDGE_API_KEY='your-judge-key'
export JUDGE_MODEL_NAME='gpt-5'

make setup-obs-evals      # obs-setup + expose-obs (port-forwards)
make run-obs-evals
```

--------------------------------

### Run kubevirt suite locally with Claude Code (ACP)

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/README.md

End-to-end steps to build the server, install eval tooling, create a cluster, install KubeVirt, start the MCP server, run the kubevirt suite with the acp-anthropic agent on Sonnet, and tear down. Requires kubectl, a Kubernetes cluster, and the claude CLI signed in. KUBECONFIG must be exported so setup and verify.sh steps target the same cluster.

```bash
# 1. Build the server and install the eval tooling
make build mcpchecker claude-agent-acp

# 2. Create a cluster and point KUBECONFIG at it.
#    KUBECONFIG must be EXPORTED so both the kubernetes extension's setup steps
#    and each task's verify.sh kubectl target the same cluster.
make minikube-create-cluster MINIKUBE_PROFILE=mcp-eval-cluster
export KUBECONFIG="$PWD/_output/kubeconfig"

# 3. Install KubeVirt (only needed for the kubevirt suite).
#    This also auto-deploys the common-instancetypes (u1.small, u1.medium, ...)
#    via virt-operator, so instancetype tasks work without a separate step.
make kubevirt-install

# 4. Start the MCP server with the toolsets the suite needs
make run-server TOOLSETS=core,config,kubevirt

# 5. Run the suite. AGENT selects the agent, SUITE selects the tasks, MODEL sets
#    ANTHROPIC_MODEL for ACP agents. Add EVAL_TASK_FILTER=<name> to run one task.
make run-evals SUITE=kubevirt AGENT=acp-anthropic MODEL=sonnet

# 6. Tear down
make stop-server
make minikube-delete-cluster MINIKUBE_PROFILE=mcp-eval-cluster
```

--------------------------------

### kubernetes-mcp-server configuration usage examples

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Shows how to launch kubernetes-mcp-server with a main config file, environment variable, drop-in directory, or stdin. The stdin example sets port and read_only in HTTP mode only.

```bash
# Use a main configuration file
kubernetes-mcp-server --config /etc/kubernetes-mcp-server/config.toml
# or
MCP_CONFIG_PATH=/etc/kubernetes-mcp-server/config.toml kubernetes-mcp-server

# Use only drop-in configuration files (no main config)
kubernetes-mcp-server --config-dir /etc/kubernetes-mcp-server/conf.d/

# Use both main config and explicit drop-in directory
kubernetes-mcp-server --config /etc/kubernetes-mcp-server/config.toml \
                      --config-dir /etc/kubernetes-mcp-server/config.d/

# Read the main configuration from stdin (HTTP mode only)
cat <<EOF | kubernetes-mcp-server --config -
port = "8080"
read_only = true
EOF
```

--------------------------------

### Manual steps for debugging obs evals

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/obs/README.md

Same flow as the one-command reproducer but broken into individual make targets for debugging. Starts the MCP server with the observability toolset config and runs the obs eval suite, then stops the server and backends.

```bash
make minikube-create-cluster
export KUBECONFIG="$PWD/_output/kubeconfig"
make obs-setup            # Prometheus, Tempo Operator, Loki Operator
make expose-obs           # port-forward all backends
make run-server TOOLSETS='observability/metrics,observability/traces,observability/logs,observability/otelcol' \
  MCP_CONFIG_DIR=dev/config/mcp-configs
make run-evals SUITE=obs
make stop-server stop-obs
```

--------------------------------

### Example TOML configuration

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Example TOML configuration showing log level, read-only mode, toolsets, denied resources, and telemetry settings. Denied resources restrict access to sensitive resource types.

```toml
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"
```

--------------------------------

### Set up local environment with make local-env-setup

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/KEYCLOAK_OIDC_SETUP.md

Runs the complete local development environment setup: installs tools, creates a Minikube cluster with OIDC configuration, deploys Keycloak, configures realm and clients, builds the MCP server binary, generates _output/config.toml, and adds a managed keycloak.keycloak.svc entry to /etc/hosts.

```bash
make local-env-setup
```

--------------------------------

### Start Kubernetes MCP server with TOML config

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Start the server with a TOML configuration file. The --config flag specifies the path to the configuration file.

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

--------------------------------

### Run MCP Server with config.toml

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/ENTRA_ID_SETUP.md

Starts the MCP server with the specified configuration file. Run this command from the project directory after building the server.

```bash
./kubernetes-mcp-server --config config.toml
```

--------------------------------

### Run with --config-dir alone

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Command to start kubernetes-mcp-server using only a drop-in directory. The directory must contain .toml files; otherwise startup and SIGHUP exit.

```bash
kubernetes-mcp-server --config-dir /etc/kubernetes-mcp-server/conf.d
```

--------------------------------

### Install Tekton Pipelines

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/tekton/README.md

Installs Tekton Pipelines in the cluster. Run this before executing any Tekton eval tasks.

```shell
make tekton-install
```

--------------------------------

### Start Keycloak port-forward and MCP server

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/KEYCLOAK_OIDC_SETUP.md

Run these commands in separate terminals after setup. The first keeps the Keycloak port-forward running; the second starts the MCP server with the generated configuration file.

```bash
# Keep this port-forward running in a separate terminal, or in a background job
make keycloak-port-forward
```

```bash
# In another terminal, start the server
./kubernetes-mcp-server --config _output/config.toml
```

--------------------------------

### Sampling examples for development, production, and disabling

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/OTEL.md

Examples for always_on (development), traceidratio (production 5%), always_off (temporarily disable), and unsetting the endpoint.

```bash
# Development: Sample everything
export OTEL_TRACES_SAMPLER=always_on

# Production: 5% sampling (good for high-traffic services)
export OTEL_TRACES_SAMPLER=traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.05

# Temporarily disable tracing
export OTEL_TRACES_SAMPLER=always_off

# Or just unset the endpoint
unset OTEL_EXPORTER_OTLP_ENDPOINT
```

--------------------------------

### OpenShift with NetObserv deployment

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/charts/kubernetes-mcp-server/README.md

Installs the chart on OpenShift with the NetObserv toolset using the example values file. The pod ServiceAccount authenticates to the Kubernetes API and the NetObserv console plugin (cluster_auth_mode: kubeconfig).

```bash
helm upgrade -i kubernetes-mcp-server oci://ghcr.io/containers/charts/kubernetes-mcp-server \
  -n kubernetes-mcp-server --create-namespace \
  -f examples/values-openshift-netobserv.yaml \
  --set ingress.host=kubernetes-mcp-server.apps.<cluster-domain>
```

--------------------------------

### Complete TOML configuration example

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Comprehensive configuration file demonstrating all major options: server settings, HTTP security, Kubernetes connection, access control, toolsets, tool filtering, overrides, denied resources, server instructions, custom prompts, telemetry, and toolset-specific configuration. Use as a reference for setting up the server.

```toml
# Server settings
log_level = 2
log_file = "/var/log/kubernetes-mcp-server.log"
port = "8080"
bind_address = "0.0.0.0"
list_output = "table"
max_backend_response_bytes = 4194304
max_result_bytes = 16777216
max_in_flight = 64
stateless = false
disable_localhost_protection = false

# HTTP server security
[http]
read_header_timeout = "10s"  # Slowloris protection
max_body_bytes = 16777216    # 16 MB for large K8s manifests
rate_limit_rps = 5           # Per-session rate limiting
rate_limit_burst = 10

# Kubernetes connection
kubeconfig = "/home/user/.kube/config"
kube_client_qps = 50
kube_client_burst = 100

# Access control
read_only = false
disable_destructive = true

# Toolsets
toolsets = ["core", "config", "helm", "kubevirt"]

# Tool filtering
disabled_tools = ["resources_delete"]

# Tool overrides
[tool_overrides.pods_list]
description = "List pods in the cluster. Prefer using label selectors over listing all pods when the namespace has many workloads."

# Denied resources
[[denied_resources]]
group = ""
version = "v1"
kind = "Secret"

# Server instructions for MCP clients
server_instructions = """
Use this server for Kubernetes cluster management including pods, deployments,
services, and Helm releases. This server is configured with read-only access
to Secrets.
"""

# Custom prompts
[[prompts]]
name = "debug-pod"
description = "Debug a failing pod"

[[prompts.arguments]]
name = "pod_name"
required = true

[[prompts.messages]]
role = "user"
content = "Help me debug the pod {{pod_name}}"

# Telemetry (OpenTelemetry)
[telemetry]
endpoint = "http://localhost:4317"
traces_sampler = "traceidratio"
traces_sampler_arg = 0.1

# Toolset-specific configuration
[toolset_configs.kiali]
url = "https://kiali.example.com"

[toolset_configs.helm]
allowed_registries = ["oci://ghcr.io/myorg", "https://charts.example.com"]

```

--------------------------------

### Helm install for NetObserv on OpenShift

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/NETOBSERV.md

Installs or upgrades the kubernetes-mcp-server Helm chart with NetObserv example values and sets the ingress host. Requires a cluster domain and the example values file for OpenShift NetObserv configuration.

```bash
helm upgrade -i kubernetes-mcp-server oci://ghcr.io/containers/charts/kubernetes-mcp-server \
  -n kubernetes-mcp-server --create-namespace \
  -f charts/kubernetes-mcp-server/examples/values-openshift-netobserv.yaml \
  --set ingress.host=kubernetes-mcp-server.apps.<cluster-domain>
```

--------------------------------

### One-command reproducer for NetObserv evals

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/netobserv/README.md

Deploy mock plugin, start MCP server, run evals, and clean up. Requires a Kubernetes context and API endpoint credentials.

```bash
make minikube-create-cluster   # skip if you already have kubectl context
export MODEL_BASE_URL='https://your-api-endpoint/v1'
export MODEL_KEY='your-api-key'
# Optional: separate judge endpoint (defaults to MODEL_* when unset)
export JUDGE_BASE_URL='https://your-judge-endpoint/v1'
export JUDGE_API_KEY='your-judge-key'
export JUDGE_MODEL_NAME='gpt-5'

make run-netobserv-evals
```

--------------------------------

### Start MCP Inspector for Authentication Testing

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/ENTRA_ID_SETUP.md

Launches MCP Inspector to test authentication. Requires the redirect URI to be configured as described in Step 1. After starting, set the Client ID and Scope to 'openid profile email' in the Authentication section, then click Connect and log in with Entra ID credentials.

```bash
npx @modelcontextprotocol/inspector@latest $(pwd)/kubernetes-mcp-server --config config.toml
```

--------------------------------

### helm_install

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

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

```APIDOC
## helm_install

### Description
Install (deploy) a Helm chart to create a release in the current or provided namespace.

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

--------------------------------

### TOML configuration example

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Example TOML configuration for the Kubernetes MCP server, including logging, ports, TLS settings, and stateless mode. TLS settings apply to both inbound and outbound connections; environment variables override TOML values.

```toml
log_level = 2
log_file = "/var/log/kubernetes-mcp-server.log"
port = "8080"
metrics_port = "9090"  # Separate port for metrics/stats (e.g. for network policy isolation)
list_output = "yaml"
stateless = true

# Enable TLS for HTTPS
tls_cert = "/etc/tls/tls.crt"
tls_key = "/etc/tls/tls.key"

# Enforce TLS for all connections (requires tls_cert and tls_key)
require_tls = true

# Global TLS version and cipher suites (inbound + outbound; env vars override)
tls_min_version = "1.2"
tls_cipher_suites = [
    "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
    "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384"
]
```

--------------------------------

### vm_guest_info

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Retrieves guest operating system information from a VirtualMachine's QEMU guest agent. Requires the guest agent to be installed and running inside the VM.

```APIDOC
## vm_guest_info

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

### Parameters
- **info_type** (string) - Optional - 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_create

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

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.

```APIDOC
## vm_create

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

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **autostart** (boolean) - Optional - 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) - Optional - 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.

### Response
No response details provided.
```

--------------------------------

### Install Kubernetes MCP Server with Helm

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Installs the Kubernetes MCP server using a Helm chart from the ghcr.io container registry. Configuration options such as OAuth, telemetry, and resource limits are available in the chart README and values.yaml.

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

--------------------------------

### Run all Go tests with make test

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/AGENTS.md

Runs the full Go test suite. The suite relies on sigs.k8s.io/controller-runtime's setup-envtest tooling; the first run downloads a Kubernetes envtest environment from the internet, so network access is required. Without it, some tests will fail during setup.

```bash
make test
```

--------------------------------

### Migrate HTTP server from flags to config.toml

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration-changes.md

Shows the before/after migration for an HTTP server that previously used CLI flags. The 'before' command uses flags like --port, --log-level, --kubeconfig, and --toolsets; the 'after' config.toml uses the corresponding TOML keys. The final command starts the server with --config config.toml.

```bash
# before
kubernetes-mcp-server --port 8080 --log-level 2 --kubeconfig ~/.kube/config --toolsets core,config,helm
```

```toml
# after: config.toml
port = "8080"
log_level = 2
kubeconfig = "/home/user/.kube/config"
toolsets = ["core", "config", "helm"]
```

```bash
kubernetes-mcp-server --config config.toml
```

--------------------------------

### Setup and run multicluster Kiali evals

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/KIALI.md

Commands to set up a primary-remote Kind environment, run the MCP server, and execute multicluster eval tasks. Requires Kiali master (dev image) with ai/mcp/list_clusters/ support.

```bash
# Setup (~15–30 min)
KIALI_SRC=~/dev/kiali_sources/kiali make setup-kiali-multicluster

# MCP server (terminal 1)
TOOLSETS=core,config,kiali MCP_CONFIG_DIR=dev/config/mcp-configs-multicluster make run-server

# Evals (terminal 2) — same model credentials as other mcpchecker evals
export MODEL_BASE_URL="https://api.openai.com/v1"
export MODEL_KEY="sk-..."
make run-evals-multicluster
```

--------------------------------

### Local development Makefile targets

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/AGENTS.md

Provides utilities for local development: setup a complete local environment with Minikube, tear it down, show Keycloak status and connection info for OIDC testing, and tail Keycloak logs.

```bash
# Setup a complete local development environment with Minikube cluster
make local-env-setup

# Tear down the local Minikube cluster
make local-env-teardown

# Show Keycloak status and connection info (for OIDC testing)
make keycloak-status

# Tail Keycloak logs
make keycloak-logs
```

--------------------------------

### VS Code Manual MCP Installation Commands

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Install the Kubernetes MCP server extension manually in VS Code or VS Code Insiders using the --add-mcp command. Use the appropriate command for your editor.

```shell
# 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"]}'
```

--------------------------------

### Testify Suite Example

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/dev/testing.md

Defines a test suite using testify/suite, embedding suite.Suite and running it with suite.Run(). Use this pattern to organize tests into suites.

```go
type MyTestSuite struct {
    suite.Suite
}

func (s *MyTestSuite) TestSomething() {
    s.Run("descriptive scenario name", func() {
        // test implementation
    })
}

func TestMyFeature(t *testing.T) {
    suite.Run(t, new(MyTestSuite))
}
```

--------------------------------

### Install the Chart with helm upgrade

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/charts/kubernetes-mcp-server/README.md

Installs the kubernetes-mcp-server chart from the OCI registry into the kubernetes-mcp-server namespace, creating it if needed. The ingress.host value must be set unless Ingress is disabled and another exposure mechanism is used.

```shell
helm upgrade -i -n kubernetes-mcp-server --create-namespace kubernetes-mcp-server oci://ghcr.io/containers/charts/kubernetes-mcp-server --set ingress.host=<hostname>
```

--------------------------------

### Cursor mcp.json Configuration

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Add the kubernetes-mcp-server to the mcpServers list in the mcp.json file for manual installation in Cursor.

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

--------------------------------

### verify_instancetype_prefix: Check instancetype prefix

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/kubevirt/helpers/README.md

Verifies that the instancetype starts with a specific prefix (e.g., performance family like 'c1'). Returns success even if the prefix does not match, printing a warning only.

```bash
verify_instancetype_prefix "my-vm" "vm-test" "c1" "compute-optimized"
verify_instancetype_prefix "my-vm" "vm-test" "u1" "general-purpose"
```

--------------------------------

### Cluster Provider Configuration (TOML)

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Configures cluster provider-specific settings via the `cluster_provider_configs` map. The example shows a placeholder for kcp-specific configuration.

```toml
[cluster_provider_configs.kcp]
# kcp-specific configuration
```

--------------------------------

### Configure MCP Prompt via Helm Chart with Escaped Placeholders

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/prompts.md

Shows how to define a prompt through the Helm chart's config.prompts value. Because Helm's tpl renders the configuration, placeholders must be escaped as {{`{{name}}`}} to pass through unchanged. This example uses a required 'name' argument and a user message.

```yaml
config:
  prompts:
    - name: check-pod-logs
      description: Show the logs for a pod
      arguments:
        - name: name
          required: true
      messages:
        - role: user
          content: 'Show me the logs for pod {{`{{name}}`}}'

```

--------------------------------

### View Keycloak Logs with make keycloak-logs

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/KEYCLOAK_OIDC_SETUP.md

Shows the logs for the Keycloak deployment.

```bash
make keycloak-logs
```

--------------------------------

### Run Kubernetes MCP server with uvx

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Use uvx to run the Kubernetes MCP server if you have uv and python installed. The --help flag displays usage information.

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

--------------------------------

### Implement GetPrompts() method for toolset prompts

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/prompts.md

Defines a toolset prompt by implementing the GetPrompts() method. Returns a slice of api.ServerPrompt with a config.Prompt definition and a handler that builds messages dynamically from arguments. Config-defined prompts override toolset prompts with the same name.

```go
func (t *MyToolset) GetPrompts() []api.ServerPrompt {
    return []api.ServerPrompt{
        {
            Prompt: config.Prompt{
                Name:        "my-workflow",
                Description: "Custom workflow for my toolset",
                Arguments: []config.PromptArgument{
                    {
                        Name:        "namespace",
                        Description: "Target namespace",
                        Required:    true,
                    },
                },
            },
            Handler: func(params api.PromptHandlerParams) (*api.PromptCallResult, error) {
                args := params.GetArguments()
                namespace := args["namespace"]

                // Build messages dynamically based on arguments
                messages := []api.PromptMessage{
                    {
                        Role: "user",
                        Content: api.PromptContent{
                            Type: "text",
                            Text: fmt.Sprintf("Help me with namespace: %s", namespace),
                        },
                    },
                }

                return api.NewPromptCallResult("Workflow description", messages, nil), nil
            },
        },
    }
}
```

--------------------------------

### Claude Desktop npx Configuration

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Add the kubernetes-mcp-server to the mcpServers list in claude_desktop_config.json. Requires npm installed and access to a Kubernetes cluster.

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

--------------------------------

### NetObserv MCP configuration for port-forward

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/netobserv/README.md

Configuration file pointing the netobserv toolset to the local port-forward. Ensure the URL and insecure flag match your setup.

```toml
[toolset_configs.netobserv]
url = "http://127.0.0.1:9001"
insecure = true
```

--------------------------------

### Deploy MCP server with NetObserv on OpenShift

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/charts/kubernetes-mcp-server/examples/README.md

Deploys the MCP server on OpenShift with NetObserv using the provided values file. Run from the chart directory. The command installs or upgrades the release, creates the namespace if needed, and sets the ingress host to your cluster domain.

```bash
cd charts/kubernetes-mcp-server

helm upgrade -i kubernetes-mcp-server . \
  -n kubernetes-mcp-server --create-namespace \
  -f examples/values-openshift-netobserv.yaml \
  --set ingress.host=kubernetes-mcp-server.apps.<cluster-domain>
```

--------------------------------

### execute_instant_query

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Executes a PromQL instant query to get current/point-in-time values. Prerequisite: You MUST call list_metrics first to verify the metric exists.

```APIDOC
## execute_instant_query

### Description
Execute a PromQL instant query to get current/point-in-time values. Prerequisite: You MUST call list_metrics first to verify the metric exists.

### Parameters
No parameters are documented in the source.
```

--------------------------------

### TOML: Access control options (read_only, disable_destructive, experimental_enable_target_compatibility_tool_filters)

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Example configuration for enforcing least privilege. read_only=true exposes only read-only tools; disable_destructive=true disables delete/update tools but has no effect when read_only is true; experimental_enable_target_compatibility_tool_filters hides tools requiring unavailable API groups (experimental, subject to change).

```toml
# Production-safe configuration
read_only = true

# Or allow writes but prevent deletions
disable_destructive = true

# Probe every target for API-group compatibility
experimental_enable_target_compatibility_tool_filters = true
```

--------------------------------

### vm_console_screenshot

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

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.

```APIDOC
## vm_console_screenshot

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

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **name** (string) - Required - The name of the virtual machine.
- **namespace** (string) - Required - The namespace of the virtual machine.

### Response
Returns a PNG image of the VM's console.
```

--------------------------------

### Build and test

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/CONTRIBUTING.md

Build the project and run the test suite to verify your changes.

```bash
make build
make test
```

--------------------------------

### Run Kubernetes MCP server with npx

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Use npx to run the Kubernetes MCP server if you have npm and node installed. The --help flag displays usage information.

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

--------------------------------

### Add MCP server with claude mcp add-json

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/getting-started-claude-code.md

Registers the Kubernetes MCP Server with Claude Code using the claude mcp add-json command. Uses npx to run the latest version, sets the config file path, and sets KUBECONFIG to the kubeconfig created in the Getting Started guide. The -s user flag makes it available in all projects.

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

--------------------------------

### Server Instructions: Provide Hints to MCP Clients

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Set instructions for MCP clients (like Claude Code) on when to use this server. Useful for clients that support MCP Tool Search. The example lists supported tasks including Pods, Resources, Namespaces, Nodes, Events, Helm, KubeVirt, and Cluster config.

```toml
server_instructions = """
Use this server for Kubernetes and OpenShift cluster management tasks including:
- Pods: list, get details, logs, exec commands, delete
- Resources: get, list, create, update, delete any Kubernetes resource
- Namespaces and projects: list, create, switch context
- Nodes: list, view logs, get resource usage statistics
- Events: view cluster events for debugging
- Helm: install, upgrade, uninstall charts and releases
- KubeVirt: create and manage virtual machines
- Cluster config: view and switch kubeconfig contexts
"""
```

--------------------------------

### Memory Bounds TOML Example

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Sets process-wide memory caps for backend responses, tool results, and in-flight requests. Each option is reloadable; 0 disables a limit. Applies to stdio and HTTP.

```toml
max_backend_response_bytes = 4194304
max_result_bytes = 16777216
max_in_flight = 64
```

--------------------------------

### Prompts: Define Custom MCP Prompts

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Define custom MCP prompts for workflow templates. Each prompt requires name, description, and messages; arguments are optional. The example defines a 'check-pod-logs' prompt with two arguments and a user/assistant message pair.

```toml
[[prompts]]
name = "check-pod-logs"
title = "Check Pod Logs"
description = "Quick way to check pod logs"

[[prompts.arguments]]
name = "pod_name"
description = "Name of the pod"
required = true

[[prompts.arguments]]
name = "namespace"
description = "Namespace of the pod"
required = false

[[prompts.messages]]
role = "user"
content = "Show me the logs for pod {{pod_name}} in {{namespace}}"

[[prompts.messages]]
role = "assistant"
content = "I'll retrieve and analyze the logs for you."
```

--------------------------------

### Build the binary

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/CONTRIBUTING.md

Runs clean, tidy, format, lint, and build. The resulting executable is kubernetes-mcp-server.

```bash
# Clean, tidy, format, lint, and build the binary
make build
```

--------------------------------

### Reload configuration with SIGHUP

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Send a SIGHUP signal to the running kubernetes-mcp-server process to reload configuration at runtime. Requires the server to be started with --config or --config-dir; otherwise SIGHUP is ignored. The commands find the process ID, send the signal, or use pkill.

```bash
# Find the process ID
ps aux | grep kubernetes-mcp-server

# Send SIGHUP to reload configuration
kill -HUP <pid>

# Or use pkill
pkill -HUP kubernetes-mcp-server
```

--------------------------------

### Access Keycloak Admin Console via Port-Forward

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/KEYCLOAK_OIDC_SETUP.md

Starts a port-forward and opens the Keycloak admin console at https://keycloak.keycloak.svc:8443. Default admin credentials are username 'admin' and password 'admin'. Navigate to the 'openshift' realm to view or modify configuration.

```bash
make keycloak-port-forward
# Then open https://keycloak.keycloak.svc:8443
```

--------------------------------

### Enable specific toolsets in TOML configuration

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Configure the `toolsets` field in a TOML configuration file to enable only the needed toolsets. The default value is `["core", "config"]`. This example enables `core`, `config`, `helm`, and `kubevirt` toolsets.

```toml
# Enable specific toolsets
toolsets = ["core", "config", "helm", "kubevirt"]
```

--------------------------------

### Build with Makefile targets

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/AGENTS.md

Use `make build` to format source and build the binary, or `make build-all-platforms` to build for all supported platforms. The resulting executable is `kubernetes-mcp-server`.

```bash
# Format source and build the binary
make build

# Build for all supported platforms
make build-all-platforms
```

--------------------------------

### Start MCP Inspector with custom CA for OAuth flow

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/KEYCLOAK_OIDC_SETUP.md

Launches MCP Inspector in a third terminal to test the HTTP OAuth flow. The NODE_EXTRA_CA_CERTS environment variable points to the custom CA certificate so Inspector's Node.js backend can fetch Keycloak metadata through the local port-forward.

```bash
NODE_EXTRA_CA_CERTS="$(pwd)/_output/cert-manager-ca/ca.crt" \
  npx @modelcontextprotocol/inspector@latest
```

--------------------------------

### Run with mcp-inspector

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/AGENTS.md

Build the binary and run it via `mcp-inspector` for interactive testing. The command uses `npx` to launch the inspector with the built binary.

```bash
make build
npx @modelcontextprotocol/inspector@latest $(pwd)/kubernetes-mcp-server
```

--------------------------------

### Verify Tekton Installation

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/tekton/README.md

Verifies that Tekton Pipelines is installed and the tekton.dev/v1 CRDs are available.

```shell
make tekton-status
```

--------------------------------

### obs.toml configuration for port-forwards

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/obs/README.md

Configures the observability MCP toolsets to use the local port-forwards. Sets `auth_mode = "kubeconfig"` and `insecure = true` for all toolsets, with Prometheus on 9090, Alertmanager on 9093, Tempo on 3200, and Loki on 3100.

```toml
[toolset_configs."observability/metrics"]
auth_mode = "kubeconfig"
insecure = true
prometheus_url = "http://127.0.0.1:9090"
alertmanager_url = "http://127.0.0.1:9093"

[toolset_configs."observability/traces"]
auth_mode = "kubeconfig"
insecure = true
tempo_url = "http://127.0.0.1:3200"

[toolset_configs."observability/logs"]
auth_mode = "kubeconfig"
insecure = true
loki_url = "http://127.0.0.1:3100"
```

--------------------------------

### TOML example showing rejected misplaced key

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/specs/config.md

Illustrates a TOML configuration where a top-level key is accidentally placed inside a table, causing the load to fail. The error names the file and key path. This demonstrates that after merge, every remaining key must match the schema.

```toml
[http]
read_header_timeout = "10s"
port = "8080"   # intended top-level; parsed as http.port — rejected
```

--------------------------------

### Run evals by suite with make run-evals

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/README.md

Use the SUITE make variable to select which tasks run. The core suite uses the default builtin-openai agent; kiali requires Istio and Kiali installed; netobserv requires a mock plugin or real NetObserv; obs requires Prometheus, Tempo, Loki and port-forwards. With AGENT=acp-anthropic every suite is keyless, while builtin-* agents need the provider's API key for judge-backed tasks.

```bash
# core tasks (builtin-openai is the default AGENT)
make run-evals SUITE=core

# kiali tasks (needs Istio + Kiali installed; see `make setup-kiali`)
make run-evals SUITE=kiali AGENT=acp-anthropic MODEL=sonnet

# netobserv tasks (needs mock plugin or real NetObserv; see tasks/netobserv/README.md)
make run-evals SUITE=netobserv AGENT=builtin-openai

# obs tasks (needs Prometheus, Tempo, Loki + port-forwards; see tasks/obs/README.md)
make run-obs-evals
```

--------------------------------

### Example /stats JSON response

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/OTEL.md

Example JSON response from the /stats endpoint showing tool call counts, HTTP request counts, in-flight requests, and uptime.

```json
{
  "total_tool_calls": 42,
  "tool_call_errors": 2,
  "tool_calls_by_name": {
    "resources_list": 15,
    "pods_get": 12,
    "helm_list": 10,
    "resources_get": 5
  },
  "total_http_requests": 100,
  "http_requests_by_path": {
    "/mcp": 100
  },
  "requests_in_flight": {
    "tools/call": 3
  },
  "uptime_seconds": 3600.5
}
```

--------------------------------

### Directory structure for main config plus conf.d

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Shows a main config.toml alongside a conf.d directory. The directory is only loaded when --config-dir is passed.

```text
/etc/kubernetes-mcp-server/
├── config.toml
└── conf.d/
    ├── 00-base.toml
    ├── 10-toolsets.toml
    └── 99-local.toml
```

--------------------------------

### Verify KubeVirt VM with helper functions

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/kubevirt/helpers/README.md

Use this script to validate a KubeVirt VM after creation. It sources the helper file and runs verification functions, exiting with 1 on any critical failure. The script checks VM existence, container disk, runStrategy, instancetype, and absence of direct resources, then prints a success message.

```bash
#!/usr/bin/env bash
source "$(dirname "${BASH_SOURCE[0]}")/../../helpers/verify-vm.sh"

# Wait for VM to exist
verify_vm_exists "test-vm" "vm-test" || exit 1

# Verify container disk
verify_container_disk "test-vm" "vm-test" "fedora" || exit 1

# Verify runStrategy is used (not deprecated 'running' field)
verify_run_strategy "test-vm" "vm-test" || exit 1
verify_no_deprecated_running_field "test-vm" "vm-test" || exit 1

# Verify instancetype with size
verify_instancetype "test-vm" "vm-test" || exit 1
verify_instancetype_contains "test-vm" "vm-test" "large"

# Verify no direct resources
verify_no_direct_resources "test-vm" "vm-test"

echo "All validations passed"
exit 0
```

--------------------------------

### Run static analysis with make lint

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/AGENTS.md

Runs golangci-lint for static analysis. The lint target downloads the specified golangci-lint version if it is not already present under _output/tools/bin/.

```bash
make lint
```

--------------------------------

### kcp_workspace_describe

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Get detailed information about a specific kcp workspace.

```APIDOC
## kcp_workspace_describe

### Description
Get detailed information about a specific kcp workspace.

### Parameters
- **workspace** (string) - Required - Name or path of the workspace to describe
```

--------------------------------

### Run E2E suite with Makefile targets

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/test/e2e/README.md

Commands to set up a cluster and run the end-to-end tests. `make e2e-full-setup` creates the cluster, builds and loads the image, and installs cert-manager, Keycloak, and Kuadrant. `make e2e-test` runs the whole suite, and `E2E_ARGS` forwards flags to `go test -run` for running a subset.

```bash
# One-time: create cluster, build+load the image, install cert-manager/Keycloak/Kuadrant
make e2e-full-setup

# Run the whole suite
make e2e-test

# Run a subset (forwarded to `go test -run`)
make e2e-test E2E_ARGS='-run TestSmoke'
make e2e-test E2E_ARGS='-run TestOAuth'
```

--------------------------------

### Run server locally with npx, uvx, or binary

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/AGENTS.md

Run the server locally using `npx`, `uvx`, or direct binary execution. The server connects to the cluster specified by the kubeconfig file, `KUBECONFIG` environment variable, or defaults to `~/.kube/config`.

```bash
# Using npx (Node.js package runner)
npx -y kubernetes-mcp-server@latest

# Using uvx (Python package runner)
uvx kubernetes-mcp-server@latest

# Binary execution
./kubernetes-mcp-server
```

--------------------------------

### verify_has_resources_or_instancetype: Check resources or instancetype

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/evals/tasks/kubevirt/helpers/README.md

Verifies that the VM has either an instancetype or direct resource specification. Fails only if neither is present.

```bash
verify_has_resources_or_instancetype "my-vm" "vm-test" || exit 1
```

--------------------------------

### otelcol_get_component_schema

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Gets the JSON schema for an OpenTelemetry Collector component's configuration options.

```APIDOC
## otelcol_get_component_schema

### Description
Get the JSON schema for an OpenTelemetry Collector component's configuration options.

### Parameters
- **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) - Optional - Collector version (e.g., 'v0.100.0'). Defaults to latest available.
```

--------------------------------

### tekton_task_start

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/tekton.md

Starts a Task by creating a TaskRun. This operation is part of the Tekton toolset.

```APIDOC
## tekton_task_start

### Description
Starts a Task by creating a TaskRun.

### Method
Not specified

### Endpoint
Not specified

### Parameters
No parameters documented.

### Request Example
No request example provided.

### Response
No response details provided.
```

--------------------------------

### get_series

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Gets time series matching selectors and previews cardinality. This tool is part of the Prometheus tools suite.

```APIDOC
## get_series

### Description
Get time series matching selectors and preview cardinality.
```

--------------------------------

### Goose CLI npx Configuration

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Add the kubernetes-mcp-server to the extensions list in the goose config.yaml file. Requires npm installed.

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

--------------------------------

### Run with --config and --config-dir

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/configuration.md

Command to layer a drop-in directory on a main config file. Relative paths are resolved against the working directory independently.

```bash
kubernetes-mcp-server --config /etc/kubernetes-mcp-server/config.toml \
                      --config-dir /etc/kubernetes-mcp-server/conf.d
```

--------------------------------

### Get cluster TektonConfig with resources_get

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/docs/tekton.md

JSON payload for resources_get to retrieve the usual cluster TektonConfig resource.

```json
{"apiVersion":"operator.tekton.dev/v1alpha1","kind":"TektonConfig","name":"config"}
```

--------------------------------

### Run Kubernetes MCP server with release binary

Source: https://github.com/containers/kubernetes-mcp-server/blob/main/README.md

Run the Kubernetes MCP server using the latest release binary. The --help flag displays usage information.

```shell
# Run the Kubernetes MCP server using the latest release binary
./kubernetes-mcp-server --help
```
Tokens:
Raw