Kubernetes Mcp Server

kubernetes-mcp

An MCP (Model Context Protocol) server for Kubernetes. It lets an AI agent (Claude Code, Cursor, …) inspect and operate one or more Kubernetes clusters.

It is built on one principle: authentication and authorization stay on the Kubernetes side. The server holds only ServiceAccount credentials and every request is authorized by Kubernetes RBAC — there is no custom auth, no policy engine, no "own magic" in the MCP.

• Runs anywhere — inside a cluster (using its projected ServiceAccount token)

or standalone (using tokens + CAs for remote API servers).

• Manages many clusters from one instance; the caller picks the target with a

cluster tool argument.

• Many instances per agent — run one MCP per network zone and add them all to

your agent (see [client config](#configure-your-ai-agent)).

• Streamable-HTTP transport, deployable via the bundled Helm chart with

ESO-managed secrets.

Topology (example)

The diagram below is one example layout — the names ("My Company Tools Cluster", "Home Lab", …) are illustrative. The AI agent connects to several MCP instances (one per zone); each instance manages its own cluster and, optionally, remote clusters.

flowchart TB
    agent["Dev machine — AI agent"]
    subgraph tools["My Company Tools Cluster"]
      mcpT["MCP server"]
    end
    subgraph priv["Private Cluster"]
      mcpP["MCP server"]
    end
    subgraph home["Home Lab"]
      mcpH["MCP server"]
    end
    cA["Customer Cluster A"]
    cB["Customer Cluster B"]
    cC["Customer Cluster C"]
    agent -->|streamable-http| mcpT
    agent -->|streamable-http| mcpP
    agent -->|streamable-http| mcpH
    mcpT -->|in-cluster SA| tools
    mcpT -->|SA token + CA| cA
    mcpT -->|SA token + CA| cB
    mcpT -->|SA token + CA| cC
    mcpP -->|in-cluster SA| priv
    mcpH -->|in-cluster SA| home

Two independent levels of multiplicity: many MCP instances per agent (client config) and many clusters per instance (the server's cluster registry).

Central auth model

Two independent gates secure a call — (1) the agent authenticates to the MCP (optional, [docs/auth.md](./docs/auth.md)), and (2) the MCP's ServiceAccount is authorized by Kubernetes RBAC (always). The MCP itself holds no policy.

sequenceDiagram
    participant A as AI agent
    participant M as kubernetes-mcp
    participant K as kube-apiserver
    A->>M: tools/call + Authorization: Bearer [token]
    M->>M: (1) authenticate caller (static token / OIDC JWT)
    alt caller not authenticated
        M-->>A: 401 Unauthorized
    else authenticated
        M->>M: pick cluster from registry → its SA token + CA
        M->>K: API request (Bearer SA-token)
        K->>K: (2) RBAC authorizes the ServiceAccount
        alt allowed
            K-->>M: 200 + objects
            M-->>A: formatted result
        else denied
            K-->>M: 403 Forbidden
            M-->>A: tool error "Forbidden" (verbatim)
        end
    end
    Note over A,K: (1) client→MCP auth (optional, TLS) · (2) Kubernetes RBAC (the only cluster gate)

Cluster registry (server internals)

flowchart LR
    cfg["config.yaml(clusters: local + remotes)"] --> reg
    subgraph reg["Registry (map name → clients)"]
      c1["local(in-cluster SA)"]
      c2["customer-a(server+CA+token)"]
      c3["homelab(kubeconfig ctx)"]
    end
    tool["tool callcluster=arg"] -->|resolve| reg
    c1 --> api1["local API"]
    c2 --> api2["customer-a API"]
    c3 --> api3["homelab API"]

Each cluster entry builds a typed client, a dynamic client (for any GVK/CRD) and a REST mapper — once, up front. File-based tokens/CAs are re-read on use, so rotating (projected / ESO) credentials are picked up without a restart.

Tools

All tools take an optional cluster (defaults to the configured default cluster).

| Tool | Purpose | |------|---------| | clusters_list | list managed clusters + reachability + read-only flag | | namespaces_list | list namespaces | | resources_list | list any kind by apiVersion+kind (built-in or CRD) | | resources_get | get one object (Secret values redacted) | | pods_list | pods with phase/ready/node | | pods_log | container logs | | events_list | events, newest last | | nodes_list | nodes + readiness | | resources_apply | server-side apply a manifest | | resources_delete | delete an object | | deployment_scale | scale a Deployment | | rollout_restart | restart a Deployment/StatefulSet/DaemonSet |

* mutating — blocked when the instance or cluster is readOnly, and ultimately governed by RBAC.

Quick start (local, against your kubeconfig)

cat > /tmp/kmcp.yaml <<'EOF'
defaultCluster: dev
clusters:
  - name: dev
    kubeconfigFile: /root/.kube/config
    context: my-context
EOF
go run . --config /tmp/kmcp.yaml
# MCP endpoint: http://0.0.0.0:9090/mcp   health: /healthz /readyz

See [examples/config.yaml](./examples/config.yaml) for all three auth modes (in-cluster, explicit token+CA, kubeconfig context).

Configure your AI agent

Add one entry per MCP instance. Full examples: [examples/mcp.claude.json](./examples/mcp.claude.json), [examples/mcp.cursor.json](./examples/mcp.cursor.json).

claude mcp add --transport http k8s-tools   https://kubernetes-mcp.intern.tools.averion.zone/mcp
claude mcp add --transport http k8s-homelab https://kubernetes-mcp.homelab.example.com/mcp

Deploy (Helm + ESO)

helm install my-mcp deploy/helm/kubernetes-mcp -n kubernetes-mcp --create-namespace \
  --set localCluster.rbac.tier=read-only

Configurable RBAC tiers for the local cluster and ESO-managed remote-cluster credentials — see the [chart README](./deploy/helm/kubernetes-mcp/README.md).

ServiceAccounts for target clusters

Ready-to-apply read-only, full-access and fine-grained ServiceAccount examples, plus a script to extract the server/CA/token for the MCP config — see [docs/rbac.md](./docs/rbac.md) (manifests in [deploy/rbac/](./deploy/rbac/)).

Security model

Agent → MCP auth is pluggable (see [docs/auth.md](./docs/auth.md)):

• static — shared bearer tokens (CI / scripts).
• oidc — OAuth 2.1 resource server validating Authentik/Keycloak JWTs; MCP clients discover the provider and do a browser login on first use.
• both together; disabled by default (auth.enabled: false).

Always run behind TLS when auth is enabled. Even so, prefer exposing the MCP only on a trusted / internal ingress (e.g. WireGuard) — never publicly. Defense in depth: a global readOnly switch and per-cluster readOnly flag can disable all mutations regardless of RBAC. Note that agent auth is separate from cluster auth (ServiceAccount + RBAC) — the two are independent layers.

Metrics

Prometheus metrics on a separate, unauthenticated port (default :9091, metricsAddr): per-tool usage/latency/errors, agent-auth outcomes, per-cluster apiserver calls (client-go, with status codes) + reachability, write-guard blocks, and Go/process runtime. Not behind the /mcp auth or the public ingress — scrape it in-cluster (chart serviceMonitor.enabled). See [docs/metrics.md](./docs/metrics.md).

Testing

make test            # unit tests (fake clients)
make test-e2e        # E2E: real kube-apiserver (envtest) driven through the MCP
make test-e2e-kind   # E2E: real kind cluster, real pod logs

See [docs/architecture.md](./docs/architecture.md) for more detail and [docs/environments-integration.md](./docs/environments-integration.md) for deploying via the environments GitOps repo.

Development

Go 1.25, official MCP Go SDK, client-go. Layout: internal/config (config), internal/clusters (registry + credentials), internal/k8s (generic GVK access), internal/mcpserver (tools), internal/auth (agent-side static/OIDC authentication).

License

[Apache License 2.0](./LICENSE).

Source & license

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

• Author: truepace-io-oss
• Source: truepace-io-oss/kubernetes-mcp-server
• License: Apache-2.0

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