K8scortex Mcp

io.github.apatilgtn由 GitHub 账号 apatilgtn 发布v1.1.3更新于 Oct 29, 2026

Kubernetes MCP server: 75 tools for GKE, AKS, EKS, RBAC, audit logging, GitOps, multi-cluster.

概览

AI 生成的概览

受治理的 Kubernetes MCP 网关,提供 75 个工具,用于在 GKE、EKS、AKS、OpenShift 和本地集群上查看并安全变更工作负载。

可以做什么
  • 列出并查看工作负载、节点、StatefulSet、DaemonSet 和 Deployment,并获取 Pod 日志
  • 读取配置与诊断信息:ConfigMap、配额、事件、PVC、告警事件、HPA 状态、节点压力和有效权限
  • 执行受控写操作,例如扩缩 Deployment 或重启 Pod,默认以 dry-run 模拟方式运行
  • 通过通用读取工具列出和获取任意资源类型
  • 列出已注册集群,并跨 kubeconfig、EKS、GKE 和 Key Vault 来源比较或查看集群信息
适用场景
当助手需要排查或运维 Kubernetes 集群,而你希望用角色分级、按集群策略、默认 dry-run 和审计记录来替代直接交出 kubeconfig 时适用。适合管理多云多集群的平台团队。
运行要求
通过 npx 或已发布容器镜像以 stdio 在本地运行;需要 Node.js 22+ 和可用的 kubeconfig(KUBECONFIG,默认 ~/.kube/config)。可选 CLUSTERS_CONFIG 注册文件以接入 EKS、GKE 和 Key Vault 集群,并需要相应云凭据,如 AWS 默认凭据链、Google 应用默认凭据或 Azure 托管标识。K8SCORTEX_STDIO_ROLES 设定会话角色,默认为 platform-engineer。
安装前请注意
默认角色为 platform-engineer,会开放完整工具集;如需只读请将 K8SCORTEX_STDIO_ROLES 设为 developer。scale_deployment、restart_pod 等写工具会改变集群状态,但默认以 dry-run 运行。该服务器会读取 kubeconfig 和云凭据并签发短期 EKS/GKE 令牌,因此继承其权限;请限制身份权限并使用按集群策略。

安装

在 SourceWeft 中

  1. 打开 控制台中的 K8scortex Mcp,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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.

[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): 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):

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):

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

bash
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

bash
# Clonegit clone https://github.com/apatilgtn/k8scortex-mcp.gitcd k8scortex-mcp
# Installnpm install
# Buildnpm run build
# Run (local dev mode — auth bypassed)DISABLE_AUTH=true PORT=3001 npm run dev

Connect with MCP Inspector

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

json
{  "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:

SourceWhenClusters
CLUSTERS_CONFIG=/path/clusters.jsonSetClusters listed in the file, across any providers
Azure Key VaultAZURE_KEYVAULT_URI setThe Key Vault cluster index
kubeconfigOtherwise (or USE_LOCAL_KUBECONFIG=true)Every context in KUBECONFIG / ~/.kube/config, or the in-cluster service account

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

json
{  "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"] }  ]}
ProviderCredentialsFields
kubeconfigWhatever the context uses, including exec plugins (aws eks get-token, gke-gcloud-auth-plugin, kubelogin)context, kubeconfigPath
eksDefault AWS chain (IRSA, EKS Pod Identity, instance profile, env, SSO), optionally assuming roleArn; tokens are presigned STS URLs refreshed every 14 minutesregion, eksClusterName, roleArn
gkeApplication Default Credentials (GKE Workload Identity, service account, gcloud auth application-default login)project, location, gkeClusterName, usePrivateEndpoint
azure-keyvaultManaged identity; base64 kubeconfig in secret kubeconfig-<name> (or secretName)keyVaultUri, secretName

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):

VariableDescription
OIDC_ISSUERIssuer URL(s), comma-separated; JWKS is discovered from /.well-known/openid-configuration
OIDC_AUDIENCEExpected audience(s), comma-separated
OIDC_JWKS_URIOptional JWKS URL override
OIDC_ROLES_CLAIMClaim holding roles/groups (default roles; e.g. groups, cognito:groups, realm_access.roles)
OIDC_ROLE_MAPJSON map from IdP group names to K8sCortex roles, e.g. {"k8s-admins":"platform-engineer"}
ENTRA_TENANT_ID / ENTRA_CLIENT_IDShorthand for Entra ID (sets issuer, audience and JWKS)

Tools

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

DomainToolDescription
Workloadlist_podsList pods with status and IP
Workloadget_pod_logsFetch container logs
Workloaddescribe_deploymentFull deployment spec
Workloadlist_statefulsetsList StatefulSets with rollout status
Workloaddescribe_statefulsetDetailed StatefulSet spec/status
Workloadlist_daemonsetsList DaemonSets with scheduling status
Workloaddescribe_daemonsetDetailed DaemonSet spec/status
Workloadlist_nodesCluster nodes with Ready status
Deployscale_deploymentScale replicas (dry-run default)
Deployrestart_podDelete pod to trigger restart
Configget_configmapRead ConfigMap data
Configdescribe_namespace_quotaResource quota usage
Configlist_eventsRecent namespace events
Configlist_persistent_volume_claimsPVC status, bound volume, storage class, capacity
Configget_effective_permissionsServiceAccount SubjectAccessReview matrix
Generic Readlist_k8s_resourcesGeneric list for arbitrary resource kinds
Generic Readget_k8s_resourceGeneric get for arbitrary resource kinds
Observeget_hpa_statusHPA metrics and scaling
Observelist_warning_eventsWarning events for triage
Observeget_node_pressureNode memory/disk/PID pressure
Multilist_clustersAll registered clusters
Multiget_cluster_infoNode count, versions, architecture

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

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

来源:README.md,提交 68782ec

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

2
  1. v1.1.3最新Oct 29, 2026
  2. v1.0.2Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分