k8scortex-mcp

K8sCortex — Kubernetes MCP 服务

为 AI Agent 提供 Kubernetes 访问能力，让安全团队放心批准。 K8sCortex 是一个统一治理的 MCP 网关，支持 GKE、EKS、AKS、OpenShift 和本地集群：每个请求都进行 SSO 身份验证，设置角色层级和单集群策略，默认执行试运行，并记录谁请求了什么。

大多数 Kubernetes MCP 服务会把 kubeconfig 交给 Agent。K8sCortex 则作为中间层：它会针对每个人和每个集群，决定其 75 个工具中哪些可以运行，并记录每次调用。来自不同云的集群都位于同一注册表中，凭据按需生成。

_{这是一个真实的 Claude Code 会话，K8sCortex 是其唯一工具，运行在临时生产集群上：开发者被拒绝执行回滚，发布经理被生产环境策略拦截，SRE 修复了问题。 观看全部五个场景（97 s）：故障、发布偏差、闪购扩容、密码轮换、节点维护。录制方式。}

---

功能

• 精心整理的多领域工具集，涵盖工作负载、部署、配置、可观测性、作业、网络、GitOps、集群管理和通用读取路径
• 多云集群提供商 — kubeconfig 上下文、Amazon EKS（IAM/IRSA）、Google GKE（Workload Identity）和 Azure Key Vault，可混合注册在同一注册表中
• 多集群路由 — 使用单个 cluster 参数定位任意已注册集群；注册了多个集群时，写入操作必须显式指定集群
• 支持任意 OIDC 身份提供商（Entra ID、Okta、Cognito、Keycloak、Google），并提供单工具 RBAC（5 级角色层级）和单集群策略
• 结构化审计日志 — 记录每次工具调用的调用者身份、参数和结果
• 双传输方式 — SSE/HTTP 供程序化客户端使用，stdio 供 Claude Desktop 使用
• 短期凭据 — 按需生成 EKS 和 GKE 令牌，并仅缓存至令牌过期
• 试运行安全机制 — 破坏性工具默认采用模拟模式
• 通用读取覆盖范围 — 支持对精选写入路径之外的资源执行 list/get，避免陷入故障排查死胡同

安装

Claude Desktop、Claude Code、Cursor 和其他 MCP 客户端（stdio）

需要 Node.js 22+ 和可用的 kubeconfig。在客户端的 MCP 配置中添加以下内容（Claude Desktop：claude_desktop_config.json）：

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

developer 会启用只读会话；移除它即可使用完整工具集。使用 Claude Code 时：claude mcp add k8scortex -- npx -y k8scortex-mcp。

作为团队共享服务（HTTP + OIDC）

使用 Helm chart（默认采用只读 RBAC；如需写入功能和更多云平台，请参阅 chart README）：

helm install k8scortex ./charts/k8scortex -n platform-mcp --create-namespace \
  --set auth.oidc.issuer=https://login.example.com --set auth.oidc.audience=k8scortex

从 chart 渲染的普通清单位于 kubernetes/ 中。也可以直接运行镜像：

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

在管理集群中运行，并为云提供商配置 Workload Identity / IRSA / managed identity，在内部开放 /mcp，并将审计日志发送到 SIEM。请参阅多云设置和身份验证。

开发

前置条件

• Node.js ≥ 22（GKE 提供方的 google-auth-library 和 jwks-rsa 的 jose 依赖项需要此版本）
• Kubernetes 集群（minikube、kind、GKE、EKS、AKS 或 OpenShift）
• 已配置有效上下文的 kubectl

安装与运行

# 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

使用 MCP Inspector 连接

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

将 Claude Desktop 连接到本地构建版本

将客户端指向你的构建版本，而不是 npm 软件包：

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

重启 Claude Desktop。询问：“列出 default 命名空间中的所有 Pod”。

kubeconfig 中的每个上下文都可用作集群，因此你可以询问：“比较 kind-dev 和 prod-eks 中 Web 应用的 ArgoCD 修订版本”。设置 K8SCORTEX_STDIO_ROLES=developer，即可为本地会话启用只读工具。

---

多云设置

K8sCortex 根据环境选择集群来源：

来源	条件	集群
CLUSTERS_CONFIG=/path/clusters.json	已设置	文件中列出的集群，可来自任意提供方
Azure Key Vault	已设置 AZURE_KEYVAULT_URI	Key Vault 集群索引
kubeconfig	其他情况（或 USE_LOCAL_KUBECONFIG=true）	KUBECONFIG / ~/.kube/config 中的每个上下文，或集群内服务账户

DEFAULT_CLUSTER 用于选择工具调用未指定集群时所使用的集群。只读工具会回退到该集群；如果注册了多个集群，修改类工具必须显式指定 cluster。

集群注册表文件

{
  "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"] }
  ]
}

提供方	凭据	字段
kubeconfig	上下文使用的任何凭据，包括 exec 插件（aws eks get-token、gke-gcloud-auth-plugin、kubelogin）	context、kubeconfigPath
eks	默认 AWS 凭据链（IRSA、EKS Pod Identity、实例配置文件、环境变量、SSO），可选地假设 roleArn；令牌为预签名 STS URL，每 14 分钟刷新一次	region、eksClusterName、roleArn
gke	应用默认凭据（GKE Workload Identity、服务账户、gcloud auth application-default login）	project、location、gkeClusterName、usePrivateEndpoint
azure-keyvault	托管标识；存储在名为 kubeconfig-<name> 的机密（或 secretName）中的 base64 kubeconfig	keyVaultUri、secretName

EKS 和 GKE 提供方使用可选依赖项（@aws-sdk/client-eks、@aws-sdk/credential-providers、@smithy/signature-v4、@aws-crypto/sha256-js、google-auth-library），npm 默认会安装这些依赖项。该身份需要 eks:DescribeCluster 权限和 EKS 访问条目；或者需要 container.clusters.get 权限以及 GKE 上的 Kubernetes RBAC 权限。

按集群配置策略

策略通过名称 glob（match）和／或 labels 匹配集群，且只能收紧全局角色表：

• minRole 提高匹配集群所需的角色（appliesTo: "mutating" 可将其限制为写入工具）
• denyTools 为匹配集群上的所有用户禁用工具

compare_clusters 会针对其读取的两个集群进行检查。

身份验证

除非已配置身份提供方（或设置了 DISABLE_AUTH=true），否则 HTTP 模式不会启动：

变量	描述
OIDC_ISSUER	以逗号分隔的颁发者 URL；通过 /.well-known/openid-configuration 发现 JWKS
OIDC_AUDIENCE	以逗号分隔的预期受众
OIDC_JWKS_URI	可选的 JWKS URL 覆盖值
OIDC_ROLES_CLAIM	包含角色／组的声明（默认为 roles；例如 groups、cognito:groups、realm_access.roles）
OIDC_ROLE_MAP	将 IdP 组名映射到 K8sCortex 角色的 JSON 映射，例如 {"k8s-admins":"platform-engineer"}
ENTRA_TENANT_ID / ENTRA_CLIENT_ID	Entra ID 的简写配置（设置颁发者、受众和 JWKS）

---

工具

K8sCortex 有意对写入操作进行筛选和管控，同时允许灵活读取数据以进行诊断。

领域	工具	描述
工作负载	list_pods	列出 Pod 的状态和 IP
工作负载	get_pod_logs	获取容器日志
工作负载	describe_deployment	完整的 Deployment 规格
工作负载	list_statefulsets	列出 StatefulSet 及其发布状态
工作负载	describe_statefulset	StatefulSet 规格和状态详情
工作负载	list_daemonsets	列出 DaemonSet 及其调度状态
工作负载	describe_daemonset	DaemonSet 规格和状态详情
工作负载	list_nodes	集群节点及其 Ready 状态
部署	scale_deployment	调整副本数（默认试运行）
部署	restart_pod	删除 Pod 以触发重启
配置	get_configmap	读取 ConfigMap 数据
配置	describe_namespace_quota	资源配额使用情况
配置	list_events	命名空间近期事件
配置	list_persistent_volume_claims	PVC 状态、绑定的卷、存储类和容量
配置	get_effective_permissions	ServiceAccount SubjectAccessReview 权限矩阵
通用读取	list_k8s_resources	列出任意资源类型的通用工具
通用读取	get_k8s_resource	获取任意资源类型的通用工具
监控	get_hpa_status	HPA 指标和扩缩容情况
监控	list_warning_events	用于分类处理的警告事件
监控	get_node_pressure	节点内存、磁盘和 PID 压力
多集群	list_clusters	所有已注册的集群
多集群	get_cluster_info	节点数量、版本和架构

有关持续更新的完整目录，请参阅 docs/developer-guide.md。

---

风险管控

Kubernetes MCP 中最大的功能风险，是无法查看未纳入精选范围的资源（例如 StatefulSet、DaemonSet、PVC 或 CRD）。K8sCortex 通过结合以下方式解决这一问题：

• 受管控的写入：高影响操作保持显式，并受角色控制，且通常默认采用试运行模式。
• 灵活读取：通用读取工具支持读取任意资源类型，以便进行诊断。

这样既能维持严格的管控措施，也能满足实际故障排查需求。

---

范围界限（v1）

K8sCortex 定位为受管控的平台接口，而非不受限制的 Kubernetes 超级客户端。

• 对任意资源进行通用写入：有意不纳入 v1 范围。写入操作经过筛选，并按设计受角色控制。
• Pod exec 交互式会话：有意不纳入 v1 范围。这需要更强的会话控制和命令级审计，计划在后续版本中实现。

---

架构

Claude / IDE agents / CI-CD
        │
        ▼
┌──────────────────────────────┐
│     K8sCortex MCP Server     │
│  OIDC → RBAC → Policy → Tool │
│            → Audit           │
│         │                    │
│     Cluster Registry         │
│ kubeconfig│EKS│GKE│KeyVault  │
└──────────┬───────────────────┘
           │
    ┌──────┼──────┬──────┐
    ▼      ▼      ▼      ▼
   AKS    EKS    GKE  OpenShift / local

---

安全

• 身份验证：每次请求都会验证 OIDC 令牌（颁发者、受众和签名）；会话与创建会话的用户绑定
• 授权：基于角色的工具访问（developer → platform-engineer），并通过策略按集群进一步限制
• 审计：每次调用都会生成 JSON 结构化日志，记录用户、工具、集群、提供方和结果；机密值会被脱敏
• 网络：仅限 ClusterIP，不提供公共端点
• 凭据：短期有效的 EKS/GKE 令牌或 Key Vault kubeconfig，仅缓存至过期

---

项目结构

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

---

测试

每次推送都会运行 lint、类型检查、单元测试、身份验证/审计集成测试，以及在两个 KWOK 集群（类似 GKE 和 EKS）上执行包含 164 个场景的端到端测试矩阵。发布版本还会通过 npm run test:e2e:gke 在真实 GKE 集群上进行测试：v1.1.1 在 GKE 1.36 上通过了全部 100/100 项测试；此次测试还发现了三个 GKE 特有的错误，这些错误已在变更日志中修复。

文档

• 开发者指南 — 如何连接、可用工具和示例查询
• 运维手册 — 部署、升级、轮换凭据和事件响应
• SLO — 可用性、延迟和告警目标
• 更新日志

贡献

欢迎提交问题和拉取请求。打开 PR 前，请运行 npm run release:gate；新增工具需要在 src/roles.ts 中添加角色，并在 KWOK 矩阵中添加一个用例。

许可证

MIT