K8scortex MCP

K8sCortex — Kubernetes MCP Server

Give your AI agents Kubernetes access your security team will sign off on. K8sCortex is one governed MCP gateway for GKE, EKS, AKS, OpenShift and local clusters: SSO on every request, role tiers, per-cluster policies, dry-run by default, and an audit log of who asked for what.

Most Kubernetes MCP servers hand an agent your kubeconfig. K8sCortex sits in between: it decides, per person and per cluster, which of its 75 tools may run, and records every call. Clusters from different clouds live in one registry, with credentials minted on demand.

A real Claude Code session with K8sCortex as its only tool, on a throwaway prod cluster: the developer is denied the rollback, the release manager is blocked by the prod policy, the SRE fixes it. [Watch all five scenarios (97 s)](docs/demo/claude/claude-demo.mp4): incident, release drift, flash-sale scaling, password rotation, node maintenance. How it was recorded.

Features

• Curated multi-domain toolset across workload, deployment, configuration, observability, jobs, networking, GitOps, cluster admin, and generic read paths
• Multi-cloud cluster providers — kubeconfig contexts, Amazon EKS (IAM/IRSA), Google GKE (Workload Identity) and Azure Key Vault, mixed in one registry
• Multi-cluster routing — target any registered cluster with a single cluster parameter; writes require an explicit cluster when several are registered
• Any OIDC identity provider (Entra ID, Okta, Cognito, Keycloak, Google) with per-tool RBAC (5-tier role hierarchy) and per-cluster policies
• Structured audit logging — every tool call recorded with caller identity, arguments, and outcome
• Dual transport — SSE/HTTP for programmatic clients + stdio for Claude Desktop
• Short-lived credentials — EKS and GKE tokens are minted on demand and cached only until they expire
• Dry-run safety — destructive tools default to simulation mode
• Generic read coverage — list/get support for resources outside curated write paths to avoid troubleshooting dead-ends

Install

Claude Desktop, Claude Code, Cursor and other MCP clients (stdio)

Requires Node.js 22+ and a working kubeconfig. Add to your client's MCP configuration (Claude Desktop: claude_desktop_config.json):

{

"mcpServers": { "k8scortex": { "command": "npx", "args": ["-y", "k8scortex-mcp"], "env": { "K8SCORTEX_STDIO_ROLES": "developer" } } } }

developer gives a read-only session; remove it for the full toolset. With Claude Code: claude mcp add k8scortex -- npx -y k8scortex-mcp.

As a shared service for a team (HTTP + OIDC)

With the Helm chart (read-only RBAC by default; see the chart README for writes and more clouds):

helm install k8scortex ./charts/k8scortex -n platform-mcp --create-namespace \

--set auth.oidc.issuer=https://login.example.com --set auth.oidc.audience=k8scortex

Plain manifests rendered from the chart are in kubernetes/. Or run the image directly:

docker run -p 3000:3000 \

-e OIDC_ISSUER=https://login.example.com -e OIDC_AUDIENCE=k8scortex \ -e CLUSTERS_CONFIG=/config/clusters.json -v "$PWD/clusters.json:/config/clusters.json:ro" \ ghcr.io/apatilgtn/k8scortex-mcp:latest

Run it in a management cluster with Workload Identity / IRSA / managed identity for the cloud providers, expose /mcp internally, and ship the audit log to your SIEM. See Multi-cloud setup and Authentication.

Develop

Prerequisites

• Node.js ≥ 22 (the GKE provider's google-auth-library and the jose dependency of jwks-rsa need it)
• A Kubernetes cluster (minikube, kind, GKE, EKS, AKS or OpenShift)
• kubectl configured with a valid context

Install & Run

# Clone

git clone https://github.com/apatilgtn/k8scortex-mcp.git cd k8scortex-mcp

Install

npm install

Build

npm run build

Run (local dev mode — auth bypassed)

DISABLE_AUTH=true PORT=3001 npm run dev

Connect with MCP Inspector

npx @modelcontextprotocol/inspector sse http://localhost:3001/mcp

Connect Claude Desktop to a local build

Point the client at your build instead of the npm package:

{

"mcpServers": { "k8scortex": { "command": "node", "args": [" /k8scortex-mcp/dist/stdio.js"] } } }

Restart Claude Desktop. Ask: *"List all pods in the default namespace"*.

Every context in your kubeconfig is available as a cluster, so you can ask *"Compare the web app's ArgoCD revision between kind-dev and prod-eks"*. Set K8SCORTEX_STDIO_ROLES=developer to give the local session read-only tools.

Multi-cloud setup

K8sCortex picks its cluster source from the environment:

DEFAULT_CLUSTER chooses the cluster used when a tool call names none. Read-only tools fall back to it; mutating tools require an explicit cluster whenever more than one cluster is registered.

Cluster registry file

{

"defaultCluster": "dev", "clusters": [ { "name": "dev", "provider": "kubeconfig", "context": "kind-dev", "labels": { "env": "dev" } }, { "name": "prod-eks", "provider": "eks", "region": "us-east-1", "eksClusterName": "prod", "roleArn": "arn:aws:iam::111122223333:role/k8scortex", "labels": { "env": "prod" } }, { "name": "prod-gke", "provider": "gke", "project": "my-project", "location": "us-central1", "gkeClusterName": "prod", "labels": { "env": "prod" } }, { "name": "prod-aks", "provider": "azure-keyvault", "cloud": "aks", "region": "australiaeast", "keyVaultUri": "https://my-vault.vault.azure.net", "labels": { "env": "prod" } } ], "policies": [ { "labels": { "env": "prod" }, "minRole": "sre", "appliesTo": "mutating" }, { "match": "prod-*", "denyTools": ["drain_node", "delete_namespace"] } ] }

The EKS and GKE providers use optional dependencies (@aws-sdk/client-eks, @aws-sdk/credential-providers, @smithy/signature-v4, @aws-crypto/sha256-js, google-auth-library) that npm installs by default. The identity needs eks:DescribeCluster plus an EKS access entry, or container.clusters.get plus Kubernetes RBAC on GKE.

Per-cluster policies

Policies match clusters by name glob (match) and/or labels, and can only tighten the global role table:

• minRole raises the role required on matching clusters (appliesTo: "mutating" limits it to write tools)
• denyTools disables tools for everyone on matching clusters

compare_clusters is checked against both clusters it reads.

Authentication

HTTP mode refuses to start unless an identity provider is configured (or DISABLE_AUTH=true):

Tools

K8sCortex intentionally keeps writes curated and governed, while allowing flexible read access for diagnostics.

For the evolving full catalog, see docs/developer-guide.md.

Managed Risk

The largest functional risk in Kubernetes MCP is dead-end visibility on non-curated resources (for example StatefulSets, DaemonSets, PVCs, or CRDs). K8sCortex addresses this by combining:

• Governed writes: high-impact operations remain explicit, role-gated, and often dry-run by default.
• Flexible reads: generic read tools cover arbitrary resource kinds for diagnostics.

This keeps the governance posture strong while preserving practical troubleshooting coverage.

Scope Boundaries (v1)

K8sCortex is designed as a governed platform interface, not an unrestricted Kubernetes super-client.

• Generic write for any resource: intentionally out of scope in v1. Writes are curated and role-gated by design.
• Pod exec interactive sessions: intentionally out of scope in v1. This requires stronger session controls and command-level auditing that are planned for a later version.

Architecture

Claude / IDE agents / CI-CD

│ ▼ ┌───────────────────────────