
K8scortex Mcp
io.github.apatilgtnPublished by GitHub account apatilgtnv1.1.3Updated Oct 29, 2026
Kubernetes MCP server: 75 tools for GKE, AKS, EKS, RBAC, audit logging, GitOps, multi-cluster.
Overview
Governed Kubernetes MCP gateway with 75 tools for inspecting and safely changing workloads across GKE, EKS, AKS, OpenShift and local clusters.
- What you can do
- List and describe workloads, nodes, StatefulSets, DaemonSets and deployments, and fetch pod logs
- Read configuration and diagnostics: ConfigMaps, quotas, events, PVCs, warning events, HPA status, node pressure and effective permissions
- Perform curated writes such as scaling a deployment or restarting a pod, with dry-run simulation by default
- List and get arbitrary resource kinds through generic read tools
- List registered clusters and compare or inspect cluster info across kubeconfig, EKS, GKE and Key Vault sources
- When to use it
- Useful when an assistant needs to troubleshoot or operate Kubernetes clusters and you want role tiers, per-cluster policies, dry-run defaults and an audit trail instead of handing over a raw kubeconfig. Suited to platform teams running several clusters across clouds.
- Requirements
- Runs locally over stdio via npx or the published container image; needs Node.js 22+ and a working kubeconfig (KUBECONFIG, defaulting to ~/.kube/config). Optional CLUSTERS_CONFIG registry file for EKS, GKE and Key Vault clusters, plus cloud credentials such as AWS default chain, Google application default credentials or Azure managed identity. K8SCORTEX_STDIO_ROLES sets the session role and defaults to platform-engineer.
Installation
In SourceWeft
- Open K8scortex Mcp in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
K8sCortex — Kubernetes MCP Server
[CI] [npm version] [smithery badge] [License: MIT]
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): 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
clusterparameter; 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):
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):
Plain manifests rendered from the chart are in kubernetes/. Or run the image directly:
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-libraryand thejosedependency ofjwks-rsaneed it) - A Kubernetes cluster (minikube, kind, GKE, EKS, AKS or OpenShift)
kubectlconfigured with a valid context
Install & Run
Connect with MCP Inspector
Connect Claude Desktop to a local build
Point the client at your build instead of the npm package:
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
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:
minRoleraises the role required on matching clusters (appliesTo: "mutating"limits it to write tools)denyToolsdisables 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
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
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 — How to connect, available tools, example queries
- Operator Runbook — Deploy, upgrade, rotate credentials, incident response
- SLOs — Availability, latency, and alerting targets
- Changelog
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
Source: README.md at commit 68782ec
Tools
0Version history
2- v1.1.3LatestOct 29, 2026
- v1.0.2Sep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts