AI导哈

Kubernetes操作工具

k8s-mcp是一个轻量级的MCP服务器，允许AI助手通过高级工作流工具部署、检查和操作Kubernetes工作负载，减少原始kubectl命令的使用，并显著降低令牌消耗。

  • by jingyanjiang
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 jingyanjiang/k8s-mcp

使用说明

k8s mcp

面向代理和快速移动团队的AI原生Kubernetes操作。

k8s mcp是一款轻量级 主控程序 该服务器允许AI助手通过高级工作流工具而不是原始kubectl命令部署、检查和操作Kubernetes工作负载，并具有结构化输出，大大减少了令牌的使用。

适用于 克劳德代码 · Codex CLI · Gemini CLI · 开放代码 ·以及任何MCP兼容的代理。

少一些kubectl。做得更多。

演示

为什么存在

今天的人工智能助手可以提供建议 kubectl 命令。但实际操作集群仍然意味着切换上下文、复制粘贴命令、手动调试故障以及反复检查日志和事件。这造成了一个缓慢的人在循环中的循环。

k8s-mcp通过提供AI代理来缩小这一差距 任务完成工具 而不是低级原语。而不是链接：

kubectl get pod
kubectl describe pod
kubectl logs

代理可以调用以下工具 diagnose_pod() 或 wait_for_ready() --一次性获得结构化结果。

是什么让它与众不同

k8s mcp的设计围绕 工作流，而不是原始资源访问——针对以下方面进行了优化：

  • AI代理执行循环 --部署、观察、诊断、重试、验证
  • 较低的令牌使用率 --结构化输出而不是长shell转录
  • 初学者友好操作 --减少手动命令链
  • 更快的迭代 --“请部署此”和工作结果之间的移动部件更少

关键能力

  • 比外壳工具更快、更轻 --原生MCP工具将结构化数据直接返回给AI，避免了shell生成、CLI输出解析和大文本流
  • 一次性诊断问题 — diagnose_pod 将状态、条件、事件和失败容器日志组合到一个报告中
  • 自主部署循环 --应用清单、等待准备就绪、检测故障并迭代，无需手动来回
  • 生成部署清单 --自动创建一个可用的Kubernetes起点，而不是从头开始编写YAML
  • 查询并采取行动 --列出Pod、读取日志、检查配置、扩展部署、重新启动工作负载、应用清单以及从对话中删除资源
  • 检测配置漂移 --将实时资源导出为YAML并与本地清单进行比较
  • 设计安全 --重复使用您的 ~/.kube/config 以及您组织现有的身份验证流（SSO、OIDC、证书）。从不存储或管理凭据
  • 与任何MCP客户端一起工作 --支持stdio、HTTP和SSE传输

如何比较

一些Kubernetes MCP服务器专注于广泛的资源级API访问。k8s mcp专注于 为AI代理设计的工作流级工具.

k8s-mcp 传统mcp服务器
聚焦 工作流级工具 原始资源API
可用性 初学者友好 需要Kubernetes专业知识
输出 摘要、结构化 原始API响应
代理效率 高——调用更少，令牌使用率更低 需要更多的推理和链接

这是给谁的

  • 人工智能工程师 构建与Kubernetes交互的代理工作流
  • 研究人员 在没有深厚k8s专业知识的情况下在Kubernetes上部署模型
  • 开发者 希望从IDE自动化集群操作的人员
  • 团队 尝试人工智能驱动的DevOps

如果您想要广泛、低级别的Kubernetes API访问，还有其他MCP服务器更适合这样做。如果你想要一个真正能 操作 一个手动开销较少的集群，这个项目适合你。

快速开始

1.安装

git clone git@github.com:jingyanjiang/k8s-mcp.git
cd k8s-mcp
pipx install .

这使得 k8s-mcp 在您的PATH中，可以从任何目录运行。

您还可以使用 uv tool install . 或 pip install ..为了开发，请使用 poetry install.

2.验证您的Kubernetes访问权限

k8s mcp读取您现有的 ~/.kube/config.使用前，请验证：

kubectl auth whoami
kubectl get all -n <your-namespace>

服务器会继承kubeconfig用户拥有的任何权限。不需要其他凭据。

注： 一些操作（例如。， list_namespaces, list_nodes)需要集群范围的权限。如果请求失败 403 Forbidden，向您的集群管理员询问必要的RBAC角色。

3.添加到您的MCP客户端

克劳德代码/克劳德桌面

添加 .mcp.json （项目层面）或 ~/.claude.json （全球）：

{
  "mcpServers": {
    "k8s": {
      "type": "stdio",
      "command": "k8s-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

OpenAI Codex命令行界面

添加 ~/.codex/config.toml （用户级别）或 .codex/config.toml （项目层面）：

[mcp_servers.k8s]
command = "k8s-mcp"
args = ["--transport", "stdio"]

Gemini CLI

添加 ~/.gemini/settings.json （用户级别）或 .gemini/settings.json （项目层面）：

{
  "mcpServers": {
    "k8s": {
      "command": "k8s-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

开放代码

添加 opencode.json 在项目根目录中：

{
  "mcp": {
    "k8s": {
      "type": "local",
      "command": ["k8s-mcp", "--transport", "stdio"]
    }
  }
}

如果您的MCP客户端找不到 k8s-mcp 在PATH中，使用绝对路径（运行 which k8s-mcp 找到它）。

当您的MCP客户端连接时，服务器会自动启动，无需手动命令。

Using Poetry instead of a global install?

替换 "command": "k8s-mcp" 随着 "command": "poetry" 并将args设置为 ["run", "k8s-mcp", "--transport", "stdio"]。您还必须添加 "cwd": "/absolute/path/to/k8s-mcp" 这样诗才能找到项目。

Other transport modes

服务器支持三种传输模式：

# stdio (for local MCP clients like Claude Code)
k8s-mcp --transport stdio

# Streamable HTTP (for remote/networked clients)
k8s-mcp --transport streamable-http

# SSE (Server-Sent Events)
k8s-mcp --transport sse

对于HTTP传输，通过环境变量配置绑定地址和端口：

export K8S_MCP_HOST=0.0.0.0   # default: localhost
export K8S_MCP_PORT=8000       # default: 8000

4.（可选）安装 k8s-ops Claude Code的技能

对于Claude Code用户来说，这个仓库提供了一种固执己见的工作流技能 技能/k8s操作/。它对多步骤剧本进行编码 部署, 调试, 推出，以及 审计 在原始MCP工具之上，当您希望代理遵循测试序列（例如，调试决策树、飞行前部署检查）而不是即兴创作时，这很有用。

使用符号链接安装，以便从更新 git pull 自动流过：

ln -s "$(pwd)/skills/k8s-ops" ~/.claude/skills/k8s-ops

然后在Claude Code中，用以下命令调用它 /k8s-ops （例如。， /k8s-ops debug, /k8s-ops audit NAMESPACE=foo).该技能也是模型调用的——当您要求代理部署、诊断、重启或审计Kubernetes工作负载时，它会自动激活。

如果您使用的是其他MCP客户端，请跳过此步骤。MCP服务器本身在没有它的情况下工作。

5.试试看

Please check the status of my namespace: <namespace>

Please deploy the app in this repo to my k8s cluster. Make a plan first, then implement it.

My pods in namespace X keep crashing. Can you figure out what's wrong?

示例用例

检查集群状态

“请检查我的命名空间的状态：xxxxx”

助手将列出命名空间中的Pod、部署、服务和事件，并发现任何问题。

部署应用程序

“请为我将此仓库中的应用程序/服务器部署到k8s集群。先制定计划，然后实施。”

代理人将：

  1. 分析回购结构
  2. 确认目标集群、命名空间、映像注册表和标记
  3. 生成Kustomize清单
  4. 应用部署
  5. 等待准备就绪并返回结构化健康结果

诊断失败的工作负载

“我在命名空间X中的Pod一直崩溃。你能找出问题所在吗？”

代理将检查pod状态、条件、事件和容器日志，然后返回一个结构化的解释和建议的修复。不再手动运行 describe 和 logs 在一个循环中。

工具

签名工具

这些最能代表项目的面向工作流的设计：

工具 说明
diagnose_pod 一次性诊断——结合状态、条件、事件和故障容器日志
wait_for_ready 轮询pod或部署，直到就绪或超时（启用自主部署循环）
apply_manifest 应用YAML清单（创建或更新，支持多文档）
apply_kustomize 渲染并应用Kustomize目录（相当于 kubectl apply -k)
get_resource_yaml 将实时资源导出为干净的YAML（用于配置漂移检测）
generate_deploy_manifests 生成Kubernetes清单，用于将k8s-mcp本身部署到集群
Full tool reference

所有操作都以MCP工具的形式公开——您可以通过AI助手与它们进行对话式交互。

集群上下文

工具 说明
get_contexts 列出可用的kubeconfig上下文
get_current_context 显示活动上下文、集群和用户

命名空间

工具 说明
list_namespaces 列出群集中的所有命名空间

容器组

工具 说明
list_pods 列出Pod（按命名空间、标签或所有命名空间）
get_pod 获取详细的pod信息
get_pod_logs 获取容器日志（带尾部，支持以前的容器）
delete_pod 删除一个pod（具有可配置的宽限期）
diagnose_pod 一次性诊断——结合故障容器的状态、条件、事件和日志
exec_command 在正在运行的容器内执行命令（例如。， curl, env, nslookup)

部署

工具 说明
list_deployments 列出部署（按命名空间、标签或所有命名空间）
get_deployment 获取详细的部署信息
scale_deployment 将部署扩展到N个副本
restart_deployment 滚动重启（相当于 kubectl rollout restart)
get_rollout_status 检查卷展是否已完成、正在进行或卡住

服务

工具 说明
list_services 列出服务（按命名空间、标签或所有命名空间）
get_service 获取详细的服务信息

ConfigMaps

工具 说明
list_configmaps 列出ConfigMgraps（按命名空间、标签或所有命名空间）
get_configmap 获取ConfigMgr的元数据和数据内容

秘密

工具 说明
list_secrets 列出带有类型和密钥计数的秘密
get_secret 获取Secret元数据和密钥名称；可选地使用掩码对值进行解码

服务帐户

工具 说明
list_service_accounts 列出ServiceAccounts（按命名空间、标签或所有命名空间）
get_service_account 获取ServiceAccount详细信息，包括机密和自动挂载配置

RBAC（角色和绑定）

工具 说明
list_roles 列出角色（按命名空间或全部）；可选地包括ClusterRoles
get_role 获取角色或ClusterRole详细信息，包括权限规则
list_role_bindings 列出角色绑定（按命名空间或全部）；可选地包括ClusterRoleBinding
get_role_binding 获取RoleBinding或ClusterRoleBinding详细信息，包括主题和角色参考

节点

工具 说明
list_nodes 列出具有状态和角色的群集节点
get_node 获取详细的节点信息

事件

工具 说明
list_events 列出事件，可选择按资源名称筛选

工作

工具 说明
list_jobs 列出具有完成状态和持续时间的作业

进入

工具 说明
list_ingresses 列出带有主机、类和TLS信息的入口
get_ingress 获取详细的入口信息，包括路由规则

通用操作

工具 说明
apply_manifest 应用YAML清单（创建或更新，支持多文档）
apply_kustomize 渲染并应用Kustomize目录（相当于 kubectl apply -k)
delete_resource 按类型和名称删除任何资源（支持缩写，如 po, svc, deploy)
describe_resource 描述任何资源——将规范/状态与相关事件（如 kubectl describe)
get_resource_yaml 将实时资源导出为干净的YAML（用于配置漂移检测）

资源指标

工具 说明
top_pods 显示每个pod的CPU/内存使用情况（需要指标服务器）
top_nodes 用容量百分比显示每个节点的CPU/内存使用情况

准备就绪

工具 说明
wait_for_ready 轮询pod或部署，直到就绪或超时（启用自主部署循环）

部署生成

工具 说明
generate_deploy_manifests 生成Kubernetes清单，用于将k8s-mcp本身部署到集群

安全

k8s mcp的设计具有实用的保障措施：

  • 命名空间范围 --代理在采取行动之前确认目标命名空间
  • 破坏性行动确认 --删除、缩放到零和重新启动操作需要明确的用户批准
  • 默认情况下为只读查询 --大多数工具都是非破坏性的

在生产环境中应用更改之前，始终审查操作。

项目状态

该项目正在积极维护和发展。欢迎反馈、建议和贡献。

贡献

欢迎提出请求和想法。如果你正在尝试人工智能驱动的DevOps，我很想知道哪些工作流程会有用。

许可证

麻省理工学院

相关 MCP