K8s Mcp Go

k8s-mcp-go

Safe, read-only-by-default Kubernetes access for AI agents.

A Kubernetes MCP server that lets AI assistants inspect your cluster safely — without giving them unrestricted kubectl.

What makes it different

• Read-only by default: useful for diagnosis without giving AI permission to mutate the cluster.
• Explicit permission modes: choose readonly, readwrite, or dangerous before the assistant starts.
• No Docker required: install via MCPB bundles or a single native binary.
• Kubernetes-native visibility: inspect pods, deployments, services, logs, events, nodes, and live CPU/memory usage.
• Registry-ready distribution: published as io.github.kaneg/k8s-mcp-go for MCP Registry consumers and packaged clients.

Distribution

• MCP Registry: published as io.github.kaneg/k8s-mcp-go.
• PulseMCP: indexed from the MCP ecosystem with the official server.json.
• Claude Code Marketplaces: listed with MCPB installation metadata.

Why

Most AI agents can use Kubernetes tools. The real problem is how to stop them from changing the wrong thing.

Giving an AI raw kubectl access is risky. Even a capable model can:

• delete the wrong resource
• restart the wrong workload
• apply a dangerous change
• turn a debugging session into a production incident

k8s-mcp-go gives AI agents a guardrailed interface to Kubernetes instead of unrestricted shell access.

It is built for the real-world question:

> How can I let AI help with Kubernetes, without letting it break my cluster?

Permission Modes

You choose the boundary up front:

| What you want | Mode | |---------------|------| | "Let AI inspect and diagnose, but change nothing" | readonly | | "Allow safe operational actions like scale and restart" | readwrite | | "Give it full cluster power" | dangerous |

readonly (default)

For diagnosis, inspection, and safe exploration.

AI can do things like:

• list pods, deployments, services, nodes, and namespaces
• read logs and events
• inspect cluster state
• check resource usage

It cannot modify workloads or delete resources.

readwrite

For controlled operational workflows.

AI can do things like:

• scale deployments
• restart deployments
• restart statefulsets
• update images
• patch deployments
• create namespaces

It still cannot perform the most destructive operations.

dangerous

Full access.

Use this only when you explicitly want AI to be able to:

• delete resources
• delete namespaces
• apply arbitrary YAML

If you are unsure, use readonly.

Quick Start

Option 1: MCPB Install (Recommended)

Download the .mcpb bundle for your platform from Releases. MCPB-compatible clients (Claude Desktop, Cursor, etc.) can install it directly — no Docker, no Go, no manual setup.

| OS | Arch | File | |----|------|------| | Linux | x8664 | k8s-mcp-go_*_linux_amd64.mcpb | | Linux | ARM64 | k8s-mcp-go_*_linux_arm64.mcpb | | macOS | Intel | k8s-mcp-go_*_darwin_amd64.mcpb | | macOS | Apple Silicon | k8s-mcp-go_*_darwin_arm64.mcpb | | Windows | x8664 | k8s-mcp-go_*_windows_amd64.mcpb | | Windows | ARM64 | k8s-mcp-go_*_windows_arm64.mcpb |

Option 2: Manual Binary Install

Grab the binary archive from Releases and extract it:

# Example: Linux x86_64
tar xzf k8s-mcp-go_*_linux_amd64.tar.gz
chmod +x k8s-mcp-go
sudo mv k8s-mcp-go /usr/local/bin/

Then add it to your MCP client.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "k8s": {
      "command": "k8s-mcp-go",
      "args": ["-mode=readonly"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "k8s": {
      "command": "k8s-mcp-go",
      "args": ["-mode=readonly"]
    }
  }
}

Restart your client and start asking questions about your cluster.

Example prompts

Once installed, ask your AI assistant things like:

• "Show me unhealthy pods in all namespaces."
• "Which pods are using the most memory?"
• "Summarize recent warning events."
• "Inspect this deployment and explain why it is not ready."
• "Check rollout status for this deployment."

In readonly mode, the assistant can investigate but cannot change the cluster.

Why not just use kubectl?

Because the problem is not whether AI can talk to Kubernetes. The problem is whether it can do so safely.

kubectl is powerful, but it does not give you a product-level permission mode for AI behavior. With k8s-mcp-go, you decide whether the assistant can:

• inspect only
• perform limited operational actions
• or get full control

The permission boundary is the product.

Available Tools (35 total)

Tools are grouped by permission level. Names start with an action verb such as get, list, or delete; top_nodes and top_pods retain Kubernetes' established kubectl top terminology.

Readonly (24)

| Tool | Description | |------|-------------| | get_server_info | Show server version, mode, Kubernetes config source, and runtime details | | resolve_workload | Resolve an app/workload name to matching resources and suggested next tools | | list_pods | List pods; supports all_namespaces=true | | get_pod | Get pod details | | get_pod_logs | Get pod logs | | list_deployments | List deployments; supports all_namespaces=true | | get_deployment | Get deployment details | | list_statefulsets | List StatefulSets; supports all_namespaces=true | | get_statefulset | Get StatefulSet details | | list_services | List services; supports all_namespaces=true | | get_service | Get service details | | list_configmaps | List ConfigMaps; supports all_namespaces=true | | get_configmap | Get ConfigMap data | | list_secrets | List Secrets (keys only); supports all_namespaces=true | | get_secret | Get Secret metadata and keys | | list_pvc | List PersistentVolumeClaims; supports all_namespaces=true | | list_ingress | List Ingress resources; supports all_namespaces=true | | list_jobs | List Jobs; supports all_namespaces=true | | top_nodes | Current node CPU and memory usage | | top_pods | Current pod CPU and memory usage | | list_nodes | List cluster nodes | | list_namespaces | List namespaces | | get_cluster_overview | Cluster health summary | | list_events | List events |

Readwrite (7)

| Tool | Description | |------|-------------| | scale_deployment | Scale deployment replicas | | restart_deployment | Rolling restart a deployment | | restart_statefulset | Rolling restart a statefulset | | set_image | Update container image | | get_rollout_status | Check rollout progress | | create_namespace | Create a new namespace | | patch_deployment | Apply strategic merge patch |

Dangerous (7)

| Tool | Description | |------|-------------| | delete_pod | Delete a pod | | delete_deployment | Delete a deployment | | delete_statefulset | Delete a StatefulSet and its pods | | delete_daemonset | Delete a DaemonSet and its pods | | delete_resource | Delete a resource without a dedicated delete tool | | delete_namespace | Delete a namespace and all resources | | apply_yaml | Apply arbitrary YAML manifest |

Prefer the dedicated delete tools above when one exists. Use delete_resource as the fallback for other kinds. It resolves namespaced versus cluster-scoped resources through Kubernetes discovery.

{"api_version":"v1","kind":"ServiceAccount","namespace":"apps","name":"builder"}
{"api_version":"rbac.authorization.k8s.io/v1","kind":"ClusterRole","name":"auditor"}

Kubernetes Configuration

Configuration is selected in this order:

1. The file specified by KUBECONFIG, when set.
2. The Pod's in-cluster ServiceAccount configuration.
3. ~/.kube/config when running outside a cluster.

An explicit KUBECONFIG is authoritative. If it cannot be loaded, the server returns an error instead of silently switching to the Pod's ServiceAccount. In-cluster configuration uses Kubernetes' mounted token file so projected ServiceAccount token rotation continues to work without copying tokens into a kubeconfig.

Environment Variables

| Variable | Description | |----------|-------------| | KUBECONFIG | Explicit kubeconfig path. When unset, use in-cluster configuration or fall back to ~/.kube/config. |

Build from Source

git clone https://github.com/kaneg/k8s-mcp-go.git
cd k8s-mcp-go
go build -o k8s-mcp-go .

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kaneg
• Source: kaneg/k8s-mcp-go
• License: MIT

Install and usage instructions live in the source repository linked above.