AgentMatter
EN/中文
提交项目GitHub
MCP 服务器 · 发布者仓库

Kubernetes MCP Server

用原生 Go 服务把 Kubernetes 与 OpenShift 的资源查询、Pod 诊断、事件、Helm 和可选扩展工具交给支持 MCP 的 AI 客户端，并提供只读、资源拒绝清单与 RBAC 等权限收敛手段。

2.1k StarsApache-2.0Go今天更新
安装与使用 GitHub
01

项目介绍

Kubernetes MCP Server 面向需要让 AI Agent 观察或操作 Kubernetes、OpenShift 的团队。它是原生 Go 实现，直接调用 Kubernetes API，不依赖本机安装 kubectl 或 Helm CLI；同一项目同时提供本地 stdio、容器化 Streamable HTTP、npm、PyPI 和原生二进制分发。核心价值是把通用资源、Pod、事件、Helm 与一组可选生态工具整理成 MCP 工具，但这类接入天然处在高权限边界上。仓库默认并非只读，因此更稳妥的起点是独立 ServiceAccount、最小 RBAC、专用 kubeconfig 与 --read-only，然后再按明确场景逐项放开写入工具。

02

核心功能

01

通用资源操作

通过 Kubernetes 动态 API 发现和处理常见及自定义资源；查询与写入范围由工具设置和 RBAC 共同限制。

02

Pod 诊断与操作

提供 Pod 列举、详情、日志、指标、exec、删除与临时运行等工具，适合排障但也包含高风险执行能力。

03

Helm 生命周期管理

内置 Helm 安装、列举和卸载能力，无需依赖外部 Helm CLI；应为写入操作单独设置权限和确认策略。

04

多集群与配置重载

可使用多个 kubeconfig 上下文，并在集群配置变化时重新加载，方便在受控边界内切换目标。

05

可选生态工具集

按需启用 Tekton、Kiali、KubeVirt、NetObserv 与 kcp 等工具集，减少无关工具进入模型上下文。

06

自托管与可观测性

支持 Streamable HTTP、OAuth/OIDC、指标和 OpenTelemetry 配置，适合团队部署，但网络与身份边界需自行加固。

03

安装与连接

推荐先为 MCP 创建专用只读身份与 kubeconfig，再用 npx 以 --read-only 注册到 Claude Code；连接成功后只执行无副作用的命名空间查询。

AI AGENT INSTALL

让 AI Agent 帮你安装

把这段话发送给 Codex、Claude Code 或其他可以操作本地环境的 AI Agent。

请从 https://github.com/containers/kubernetes-mcp-server 安装并配置 Kubernetes MCP Server。先阅读 README、docs/getting-started-claude-code.md、docs/getting-started-kubernetes.md 与 docs/configuration.md。不要使用我的日常管理员 kubeconfig；先确认目标集群与命名空间，再创建专用 ServiceAccount、最小只读 RBAC 和独立 kubeconfig。通过 npx 和 --read-only 接入 Claude Code，任何凭据、额外权限、文件覆盖、网络暴露或写操作都必须先征得我的明确同意。最后运行 claude mcp list，并只执行一次列出命名空间的无副作用验证，报告配置位置、身份、权限范围与结果，但不要输出 token。
01开始前准备
  • 一个正在运行且网络可达的 Kubernetes 或 OpenShift 集群
  • 用于创建 ServiceAccount 与 RBAC 的 kubectl 及相应管理员权限
  • Node.js 与 npx；也可按仓库说明改用 uvx、原生二进制或容器
  • 支持 MCP 的客户端，例如 Claude Code
  • 为 MCP 单独保存的 kubeconfig 绝对路径
02复制安装命令或配置
claude mcp add-json kubernetes-mcp-server '{"command":"npx","args":["-y","kubernetes-mcp-server@latest","--read-only"],"env":{"KUBECONFIG":"/absolute/path/to/mcp-viewer.kubeconfig"}}' -s user
03按步骤完成安装
  1. 1
    创建最小权限身份

    按 Kubernetes 指南创建专用命名空间与 ServiceAccount，例如 kubectl create namespace mcp、kubectl create serviceaccount mcp-viewer -n mcp，并优先用命名空间级 view RoleBinding；只有确有跨命名空间只读需求时才使用 ClusterRoleBinding。

  2. 2
    生成专用 kubeconfig

    按 docs/getting-started-kubernetes.md 取得短期 ServiceAccount token，把目标 API Server、CA、token 与专用上下文写入单独 kubeconfig。不要复用日常管理员配置，也不要把 token 写入资源说明或日志。

  3. 3
    以只读模式注册服务

    运行 claude mcp add-json kubernetes-mcp-server '{"command":"npx","args":["-y","kubernetes-mcp-server@latest","--read-only"],"env":{"KUBECONFIG":"/absolute/path/to/mcp-viewer.kubeconfig"}}' -s user，并把路径替换为真实绝对路径。

  4. 4
    执行无副作用验证

    运行 claude mcp list 检查 Connected，再让客户端列出命名空间。核对目标集群、身份与返回范围，确认没有创建、更新、删除或 exec 行为。

  5. 5
    按场景继续收敛

    若后续必须开放写入，先用 toolsets、enabled_tools、disabled_tools、denied_resources 和 confirmation_fallback=deny 建立明确边界，再为单一操作补充最小 RBAC。

如何确认安装成功

运行 claude mcp list，确认 kubernetes-mcp-server 显示 Connected；随后让客户端仅列出命名空间，并核对返回对象属于预期集群且没有产生资源变更。

使用前注意
  • read_only 默认值为 false，初次接入应显式传入 --read-only。
  • 如需部分写入，优先使用 disable_destructive、enabled_tools、disabled_tools 与 denied_resources 缩小范围。
  • 客户端不支持 elicitation 时 confirmation_fallback 默认 allow；写入部署应显式改为 deny。
  • 短期 ServiceAccount token 会过期，续期后要同步更新专用 kubeconfig。
  • HTTP 模式默认不强制 OAuth；跨主机暴露前应配置 TLS、OAuth/OIDC 和网络访问控制。
04

使用场景

SCENARIO 01

集群状态问答

让 Agent 汇总命名空间、工作负载、资源状态和事件，作为只读巡检或值班上下文。

SCENARIO 02

Pod 故障排查

在受控身份下组合 Pod 详情、日志、指标与事件，缩短定位 CrashLoop、调度或资源瓶颈的路径。

SCENARIO 03

多集群运维辅助

通过多个受限 kubeconfig 上下文查询不同集群，并要求 Agent 在每次操作前明确目标。

SCENARIO 04

受审查的 Helm 操作

在独立环境中为安装或卸载建立专门 RBAC、工具白名单与拒绝式确认回退，再由 Agent 生成并执行明确计划。

05

使用评价

从公开实现和文档看，这个项目的优势是分发方式齐全、Kubernetes 能力覆盖广，并把权限收敛、资源过滤、OAuth/OIDC 与可观测性放进同一套配置体系。需要特别警惕的是默认模式可写，且客户端缺少 elicitation 时确认回退默认允许。它适合作为经过 RBAC 设计的运维接口，不适合拿管理员 kubeconfig 直接接入生产 Agent。

值得一试的地方

  • 原生 Go 直接访问 Kubernetes API，减少对 kubectl 与 Helm CLI 的运行时依赖
  • npm、PyPI、原生二进制、容器和 Helm Chart 覆盖常见交付路径
  • 从只读、破坏性工具开关到资源拒绝清单，权限收敛手段较完整
  • 文档包含 Claude Code、桌面客户端、集群部署、OAuth/OIDC、日志与 OpenTelemetry 指南
  • 仓库包含单元、端到端和 MCP conformance 测试目录

使用前要知道

  • 默认 read_only=false 与 confirmation_fallback=allow 不适合无审查直连生产集群
  • 专用 kubeconfig 与 RBAC 的创建仍需用户具备 Kubernetes 管理经验
  • 可选工具集依赖集群安装相应 CRD 或外部服务
  • 安全修复只面向最新发布版本
06

README

Kubernetes MCP Server

Overview

用原生 Go 服务把 Kubernetes 与 OpenShift 的资源查询、Pod 诊断、事件、Helm 和可选扩展工具交给支持 MCP 的 AI 客户端，并提供只读、资源拒绝清单与 RBAC 等权限收敛手段。 Model Context Protocol (MCP) server for Kubernetes and OpenShift.

Getting started

  • 推荐先为 MCP 创建专用只读身份与 kubeconfig，再用 npx 以 --read-only 注册到 Claude Code；连接成功后只执行无副作用的命名空间查询。
  • 服务直接使用 Kubernetes API，支持任意通用资源的 CRUD，并为 Pod、命名空间、事件、OpenShift Project 与 Helm 提供专用工具。
  • Pod 能力包括列举、读取、删除、日志、top、exec 与临时运行；实际可用范围由集群 API 和调用身份的 RBAC 决定。
  • 运行 claude mcp list，确认 kubernetes-mcp-server 显示 Connected；随后让客户端仅列出命名空间，并核对返回对象属于预期集群且没有产生资源变更。

Configuration

claude mcp add-json kubernetes-mcp-server '{"command":"npx","args":["-y","kubernetes-mcp-server@latest","--read-only"],"env":{"KUBECONFIG":"/absolute/path/to/mcp-viewer.kubeconfig"}}' -s user
在 GitHub 阅读完整 README →