Kubeview Mcp

KubeView MCP

用于 Kubernetes 诊断的只读 Model Context Protocol 服务。它不暴露数十种工具，而是为 Agent 提供一个沙盒化的 TypeScript 运行时：一次 run_code 调用即可查询 Kubernetes、Helm、Argo Workflows 和 Argo CD，关联结果，并仅返回答案。中间载荷不会经过模型的上下文窗口。基于 code execution with MCP 模式。

背景介绍：Evicting MCP tool calls from your Kubernetes cluster

工作原理

v2 仅发布两个公开工具：run_code 和受审批门控的 kube_pod_exec。其他所有内容都通过 tools.list()、tools.search() 和 tools.help() 在沙盒中发现，遵循 MCP 的渐进式发现与程序化调用指南。

run_code 使用顶层 await 执行受限的 TypeScript。一次调用即可列出工作负载、关联事件、获取日志并比较 Helm 状态，而无需将中间载荷传回模型：

const pods = await tools.kubernetes.list({ namespace: 'payments' });
const unhealthy = pods.items.filter((p) => p.status?.phase !== 'Running');

return Promise.all(
  unhealthy.map(async (pod) => ({
    pod: pod.metadata?.name,
    logs: await tools.kubernetes.logs({
      namespace: 'payments',
      podName: pod.metadata?.name,
      tailLines: 100,
    }),
  })),
);

• 敏感操作隔离 — 沙盒代码无法访问 kube_pod_exec。顶层 exec 需要 MCP 征询授权，绑定到参数摘要，10 分钟后过期，并采用默认拒绝策略。kube_port_forward 从不作为顶层工具提供，且默认在代码模式下被拒绝。tools.disabled() 会报告是哪项策略阻止了某项能力，以及该拒绝是否可配置。
• 由 API 驱动的发现 — Argo Workflows 和 Argo CD 会通过 Kubernetes API 检测，限定在当前 kube 上下文范围内，并缓存 60 秒。可选 API 不可用时，不会阻止启动。
• 原生读取 — 资源、指标、日志、事件和网络探测均通过 Kubernetes API 获取。Helm 发布版本通过集群 Secrets 或 ConfigMaps 解析；本地 helm 二进制只是后备方案，并非必需。

快速开始

前提条件： Node.js ≥ 22，并且可以访问集群（KUBECONFIG 或集群内服务账户）。

npx -y kubeview-mcp

# Claude Code
claude mcp add kubernetes -- npx kubeview-mcp

{
  "mcpServers": {
    "kubeview": {
      "command": "npx",
      "args": ["-y", "kubeview-mcp"]
    }
  }
}

在 Cursor 中，/kubeview/code-mode 会将类型化 API 注入上下文。

配置

集群

变量	描述	默认值
KUBECONFIG	Kubeconfig 路径；多个文件会像 kubectl 一样合并	~/.kube/config
MCP_KUBE_CONTEXT	默认上下文（名称或别名）；默认为当前活动上下文	未设置
MCP_KUBE_CONTEXTS	上下文允许列表和别名，例如 dev,staging-*,prod=arn:…/prod（详情）	所有上下文
MCP_K8S_SKIP_TLS_VERIFY	跳过 Kubernetes API 的 TLS 验证（true/1）	false
MCP_TIMEOUT	默认操作超时时间，单位为 ms	插件默认值
MCP_HIDE_SENSITIVE	全局屏蔽敏感数据	false
MCP_DISABLE_KUBERNETES_PLUGIN	禁用 Kubernetes 插件（true/1）	未设置
MCP_DISABLE_HELM_PLUGIN	禁用 Helm 插件（true/1）	未设置

模式和功能

变量	描述	默认值
MCP_MODE	code（默认）、all（别名）或 tools	code
MCP_CODE_MODE_DISABLED_TOOLS	以逗号分隔的代码模式禁用项；留空则启用全部工具	JSON/默认值
MCP_ARGO_TOOLS	Argo 覆盖选项：auto、on、off	auto
MCP_ARGOCD_TOOLS	Argo CD 覆盖选项：auto、on、off	auto
MCP_LOG_LEVEL	error、warn、info、debug	info
KUBE_MCP_FORCE_VM_SANDBOX	在独立运行时中强制使用 node:vm	未设置

HTTP 传输

变量	描述	默认值
MCP_TRANSPORT	stdio 或 http	stdio
MCP_HTTP_HOST / _PORT	HTTP 绑定地址（当 MCP_TRANSPORT=http 时）	127.0.0.1:3000
MCP_HTTP_PATH	Streamable HTTP 端点路径	/mcp
MCP_HTTP_JSON_RESPONSE	优先使用 JSON 而非 SSE（会丢弃调用过程中的通知）	false
MCP_ALLOWED_HOSTS	主机允许列表（绑定到 0.0.0.0/:: 时必需）	本地默认值
MCP_ALLOWED_ORIGINS	HTTP 的来源允许列表	未设置
MCP_APPROVAL_STATE_SECRET	共享的 32+ 字节签名密钥；HTTP 审批必需	临时值（stdio）
MCP_APPROVAL_REPLAY_DIR	用于一次性 HTTP 审批的绝对共享卷目录	未设置

mkdir -p /tmp/kubeview-mcp-approvals
MCP_APPROVAL_STATE_SECRET='replace-with-at-least-32-random-bytes' \
MCP_APPROVAL_REPLAY_DIR=/tmp/kubeview-mcp-approvals \
MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3000 npx -y kubeview-mcp

端点：http://127.0.0.1:3000/mcp。HTTP 遵循 MCP 2026-07-28 无状态核心：每个请求都会创建一个全新的服务，不使用 initialize，也不使用 Mcp-Session-Id。每个请求都会在 _meta 中携带协议版本、客户端身份和能力。现代请求会添加 Mcp-Method/Mcp-Name，用于网关路由。2025 年的客户端会在同一端点使用 SDK 的无状态回退机制。需要在调用之间保留的状态必须作为工具参数或句柄传递。

如果未设置两个审批变量，HTTP 模式将拒绝启动。多副本部署需要使用相同的密钥和可写的共享重放目录；/tmp 示例仅适用于单个进程。已发布的 MCP 注册表条目仍以 stdio 为目标。

工具接口

MCP_MODE	已公开的工具
未设置 / code / all	run_code、kube_pod_exec
tools	kube_list、kube_get、kube_logs、kube_contexts、helm、kube_pod_exec，以及检测到的 argo 和 argocd

领域工具使用 operation 判别符：

• helm — list | get | debug
• argo — list | get | logs | cron_list（可发现 Workflow 或 CronWorkflow 时）
• argocd — list | get | resources | logs | history | status（可发现 Application 时，或设置了 ARGOCD_SERVER + ARGOCD_AUTH_TOKEN 时）

发现结果会按 kube 上下文缓存 60 s。缺少可选 API 时会省略，而不会导致失败。如果默认上下文中存在 API，或者 MCP_KUBE_CONTEXTS 中列出的任意精确上下文名称中存在 API，则会注册 argo 和 argocd。

多集群

每个集群工具都接受可选的 context 参数（kubeconfig 上下文名称或 MCP_KUBE_CONTEXTS 别名）；kube_contexts 会列出可作为目标的上下文。不指定时，调用行为与之前相同：先使用 MCP_KUBE_CONTEXT，再使用 kubeconfig 的 current-context。上下文按调用设置，而非按会话设置，因此 HTTP 模式保持无状态，并允许一个脚本并发查询多个集群。

MCP_KUBE_CONTEXTS 是逗号分隔的列表。普通条目是上下文名称，可包含 * 通配符；alias=context 条目则将短名称映射到真实上下文。设置后，只能访问匹配的上下文、别名目标和 MCP_KUBE_CONTEXT；这也适用于 Helm/Argo/Argo CD CLI 回退调用，它们会收到已解析上下文对应的 --kube-context/--context。添加 * 可在定义别名的同时保留所有上下文。

MCP_KUBE_CONTEXT=dev \
MCP_KUBE_CONTEXTS='dev,staging-*,prod=arn:aws:eks:eu-west-1:123456789012:cluster/prod' \
npx -y kubeview-mcp

在 run_code 中，可通过 context 参数为整个脚本设置默认上下文，或使用 tools.withContext() 限定作用范围；单次调用的 context 始终优先：

const staging = tools.withContext('staging-eu');
const [stagingApi, prodApi] = await Promise.all([
  staging.kubernetes.diagnose({ resourceType: 'deployment', name: 'api', namespace: 'shop' }),
  tools.kubernetes.diagnose({ resourceType: 'deployment', name: 'api', namespace: 'shop', context: 'prod' }),
]);
return { staging: stagingApi.summary, prod: prodApi.summary };

kube_pod_exec 会在请求批准前解析上下文；批准提示会显示该上下文，且批准仅对该上下文有效。

代码模式

代码模式为默认模式（MCP_MODE=code）。Agent 会针对类型化的 tools 全局对象编写简短的 TypeScript 代码，而不是调用几十个 MCP 工具。

在 run_code 中：

• 用于 Kubernetes、Helm 及检测到的任何 Argo 功能的类型化 tools 命名空间，根据实时架构生成，因此参数不会凭空捏造。
• 渐进式发现：tools.list()、tools.search()、tools.help() 和 tools.disabled()（最后一个会说明功能被阻止的原因）。
• 多集群访问：tools.kubernetes.contexts()、tools.withContext(name) 和按调用设置的 context 参数（参见多集群）。
• 受限运行时，作用域内仅有 console 和 tools——没有文件系统、网络或 process。

功能	在 run_code 中	顶层工具
kube_pod_exec	永远不可用	每次调用都需要用户批准（10 min，与参数绑定）
kube_port_forward	默认拒绝（可配置）	永不公开
其他所有功能	可用	仅当 MCP_MODE=tools 时

Pod exec 批准通过 MCP elicitation 实现，并采取默认拒绝策略。独立的 npm run code-mode 启动器没有受信任的批准界面，因此始终拒绝 Pod exec。

工作负载诊断

在一次代码模式调用中诊断 Pods、Deployments、StatefulSets、DaemonSets、ReplicaSets、Jobs 和 CronJobs：

return await tools.kubernetes.diagnose({
  resourceType: 'deployment',
  name: 'payments-api',
  namespace: 'payments',
  includeLogs: true,
});

资源类型默认为 pod，并接受不区分大小写的单数或复数名称。命名空间默认为当前上下文中的命名空间，然后是 default。诊断会按 UID 追踪控制器所有权，并关联状态、事件、必需配置键、镜像拉取 Secrets、PVC 和失败容器日志。不会返回配置和 Secret 值。日志和事件文本遵循 MCP_HIDE_SENSITIVE 的设置。

要通过 CLI 诊断 Pod：

npm run command -- kube_diagnose --name monitor-eks-aid-847484f765-4hwzz

诊断控制器时，添加 --resourceType deployment（或其他受支持的类型）。如果工作负载不在当前命名空间中，则添加 --namespace。

结果包含 target、context、observedAt、health、summary、findings、evidence 和 coverage。发现项会引用证据，并区分历史故障与当前问题；可能的原因与观察到的事实分开列出。缺少可选配置属于预期情况。禁止、不可用或缺失的必需读取会保留在 coverage.errors 中；截断和跳过的读取会显示在 coverage.truncations 中。健康状态为 healthy、degraded 或 unknown；即使信息收集不完整，仍可报告已确认的故障。

自定义拒绝规则

MCP_CODE_MODE_DISABLED_TOOLS（逗号分隔）用于控制在 run_code 中屏蔽哪些功能。解析顺序：

1. MCP_CODE_MODE_DISABLED_TOOLS 环境变量
2. kube-mcp.code-mode.json 中的 disabledTools
3. 默认值：["kube_port_forward"]

空环境变量值会清空列表。无法添加 kube_pod_exec——它始终处于屏蔽状态。

协议

MCP 2026-07-28：

• 使用 JSON Schema 2020-12 定义输入／输出契约，并在服务端进行验证
• 提供机器可读的 structuredContent，并支持文本回退
• 准确标注 read-only、destructive、idempotent 和 open-world
• 工具按确定顺序排列，并为固定和依赖发现的表面提供缓存提示
• 无状态 HTTP，支持发现功能和基于标头的路由（Mcp-Method、Mcp-Name）
• 执行失败作为工具错误返回；协议错误仅用于格式错误的请求

本地开发

git clone https://github.com/mikhae1/kubeview-mcp.git
cd kubeview-mcp && npm install

npm run build      # compile
npm start          # build + run
npm test           # jest suite
npm run typecheck  # tsc --noEmit

# Invoke a tool directly
npm run command -- kube_list --namespace=default

协议测试将 SDK v2 客户端固定到 2026-07-28，并在进程内通过服务端处理程序路由（不开放端口）：

npm test -- --runInBand \
  tests/server/StreamableHttpTransport.integration.test.ts \
  tests/server/StreamableHttpRuntime.test.ts \
  tests/server/TransportConfig.test.ts \
  tests/compat/McpSdkCompatibility.test.ts

贡献

欢迎贡献！请随时提交问题或拉取请求。

许可证

MIT © mikhae1