Kubernetes diagnostics over MCP

Inspect clusters safely with the same trust model as `kubectl`.

Generic Kubernetes MCP Server is a read-only Go server for AI clients that need structured access to pods, deployments, events, logs, metrics, and ownership context without bypassing Kubernetes RBAC.

Start locally View repository

Read-only by default
Works with kubeconfig or ServiceAccount
Current transport: stdio
Release images to GHCR and Docker Hub

Why it exists

Natural-language cluster inspection without cluster-admin shortcuts

Use existing Kubernetes identity

Local mode uses the current kubeconfig context. In-cluster mode uses the Pod ServiceAccount. No hidden admin channel is introduced.

RBAC stays authoritative

Every Kubernetes read is checked with SelfSubjectAccessReview before the API call runs.

Useful troubleshooting shape

Pod inspection includes restart evidence, warnings, and owning workload context such as Pod -> ReplicaSet -> Deployment.

Architecture

Current stdio flow and future gateway flow

Current architecture

Local or in-cluster read-only access with policy and RBAC enforcement.

Current request path

Natural language
  -> MCP client
  -> generic-k8s-mcp
  -> MCP readonly policy
  -> Kubernetes RBAC check
  -> Kubernetes API read
  -> structured result back

Future gateway mode

Any MCP client
  -> HTTPS MCP gateway
  -> authentication
  -> tenant / cluster resolution
  -> policy + rate limits
  -> Kubernetes API

Tool surface

Built for troubleshooting, not mutation

Cluster and auth

cluster_info
can_i
list_namespaces
list_nodes
describe_node

Pods and workloads

list_pods
describe_pod
get_pod_logs
list_deployments
describe_deployment

Diagnostics and dynamic reads

list_events
get_resource_usage
find_unhealthy_workloads
explain_resource

By default there are no write operations, no secret reads, no pod exec, no port-forward, and no apply or patch actions.

Quickstart

Build locally and connect any stdio-capable MCP client

Build the binary

git clone https://github.com/vk7416/generic-k8s-mcp.git
cd generic-k8s-mcp
go mod tidy
make build

Check Kubernetes access

kubectl config current-context
kubectl get ns
kubectl auth can-i list pods -A
kubectl auth can-i get pods/log -n default

Run manually

./bin/k8s-mcp-server \
  --mode=local \
  --kubeconfig="$HOME/.kube/config" \
  --namespace=default \
  --readonly=true \
  --allow-secret-read=false \
  --allow-pod-command=false

Client configuration shape

{
  "mcpServers": {
    "generic-k8s": {
      "command": "/absolute/path/bin/k8s-mcp-server",
      "args": [
        "--mode=local",
        "--kubeconfig=/Users/YOU/.kube/config",
        "--context=YOUR_CONTEXT",
        "--namespace=default",
        "--readonly=true"
      ]
    }
  }
}

Container and release

Docker-packaged and tag-driven

Local Docker build

docker build -t ghcr.io/vk7416/generic-k8s-mcp:dev .
# or
make docker-build

Release flow

git checkout main
git pull
git tag v0.2.0
git push origin v0.2.0

Tags publish multi-arch images to ghcr.io/vk7416/generic-k8s-mcp and docker.io/bullraju/generic-k8s-mcp, and create a GitHub Release.

Gateway plan

What it takes to make this usable by any MCP client over the network

Add remote MCP transport

Implement Streamable HTTP while keeping stdio for local developer workflows.

Add auth and audit

Bearer token or OIDC auth, request logging, response caps, and rate limiting.

Ship one gateway per cluster first

Deploy in-cluster with a scoped ServiceAccount before attempting multi-cluster brokering.

Document remote client setup

Publish URL, auth method, timeouts, and example configs for multiple MCP clients.

Recommended first production target: one cluster, one gateway deployment, read-only only, token auth, and internal or VPN-only exposure.