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 分