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.

Claude Code, signed in as a developer, finds that checkout 1.5.0 in prod cannot reach its database and is denied the rollback; a release manager is blocked by the prod policy; an SRE previews the rollback, applies it and confirms 2/2 healthy

_{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": ["<path-to>/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
        │
        ▼
┌──────────────────────────────┐
│     K8sCortex MCP Server     │
│  OIDC → RBAC → Policy → Tool │
│            → Audit           │
│         │                    │
│     Cluster Registry         │
│ kubeconfig│EKS│GKE│KeyVault  │
└──────────┬───────────────────┘
           │
    ┌──────┼──────┬──────┐
    ▼      ▼      ▼      ▼
   AKS    EKS    GKE  OpenShift / local

Security

• Authentication: OIDC tokens (issuer, audience and signature) validated on every request; sessions are bound to the user that created them
• Authorization: Role-based tool access (developer → platform-engineer), tightened per cluster by policies
• Audit: JSON-structured log per invocation with user, tool, cluster, provider and outcome; secret values are redacted
• Network: ClusterIP only — no public endpoint
• Credentials: Short-lived EKS/GKE tokens or Key Vault kubeconfigs, cached only until expiry

Project Structure

src/
├── index.ts              # HTTP server (StreamableHTTP + SSE)
├── stdio.ts              # Stdio entry point (Claude Desktop)
├── server.ts             # Tool registry, authorization and dispatch
├── auth.ts               # OIDC middleware
├── roles.ts              # RBAC role hierarchy and per-cluster policies
├── audit.ts              # Audit logger with redaction
├── context.ts            # AsyncLocalStorage user context
├── cluster-store.ts      # Per-cluster K8s client cache
├── clusters/
│   ├── registry.ts       # Cluster registry and CLUSTERS_CONFIG loader
│   ├── kubeconfig.ts     # kubeconfig contexts provider
│   ├── eks.ts            # Amazon EKS provider
│   ├── gke.ts            # Google GKE provider
│   └── azure-keyvault.ts # Azure Key Vault provider
└── tools/                # 75 tools in 14 modules: workload, deployment, configuration,
                          # config_management, workload_creation, jobs, network, observability,
                          # resource_intelligence, cloud_awareness, cluster_admin, gitops,
                          # generic_read, multicluster

tests/
├── *.test.ts             # Unit and auth/audit integration tests (vitest)
└── e2e/
    ├── kwok/             # 164-scenario matrix on two simulated clusters (runs in CI)
    └── gke/              # Every tool, both GKE providers and policies on a real GKE cluster

charts/k8scortex/         # Helm chart for the shared HTTP service (tested on kind in CI)
kubernetes/               # The chart rendered to plain manifests, with example values
Dockerfile                # Image published to ghcr.io/apatilgtn/k8scortex-mcp

docs/
├── developer-guide.md    # End-user documentation
├── operator-runbook.md   # Platform team operations
└── slos.md               # Service level objectives

Testing

Every push runs lint, typecheck, unit tests, auth/audit integration tests and a 164-scenario end-to-end matrix on two KWOK clusters (GKE-like and EKS-like). Releases are also checked against a real GKE cluster with npm run test:e2e:gke: v1.1.1 passed 100/100 on GKE 1.36, and that run found the three GKE-specific bugs fixed in the changelog.

Documentation

• [Developer Guide](docs/developer-guide.md) — How to connect, available tools, example queries
• [Operator Runbook](docs/operator-runbook.md) — Deploy, upgrade, rotate credentials, incident response
• [SLOs](docs/slos.md) — Availability, latency, and alerting targets
• [Changelog](CHANGELOG.md)

Contributing

Issues and pull requests are welcome. Run npm run release:gate before opening a PR; new tools need a role in src/roles.ts and a case in the KWOK matrix.

License

MIT