# Kubernetes Mcp Server

> MCP server from truepace-io-oss/kubernetes-mcp-server.

- **Type:** MCP server
- **Install:** `agentstack add mcp-truepace-io-oss-kubernetes-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [truepace-io-oss](https://agentstack.voostack.com/s/truepace-io-oss)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [truepace-io-oss](https://github.com/truepace-io-oss)
- **Source:** https://github.com/truepace-io-oss/kubernetes-mcp-server

## Install

```sh
agentstack add mcp-truepace-io-oss-kubernetes-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

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

```mermaid
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)

```mermaid
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)

```bash
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).

```bash
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)

```bash
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

```bash
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](https://github.com/modelcontextprotocol/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](https://github.com/truepace-io-oss)
- **Source:** [truepace-io-oss/kubernetes-mcp-server](https://github.com/truepace-io-oss/kubernetes-mcp-server)
- **License:** Apache-2.0

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-truepace-io-oss-kubernetes-mcp-server
- Seller: https://agentstack.voostack.com/s/truepace-io-oss
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.