使用说明

⚙️ mcp-server-kubog

A Kubernetes SRE MCP Server with real-time crash monitoring powered by KOPF

Features • Architecture • Tools • Getting Started • Configuration • License

概述

mcp服务器kopf 是一个模型上下文协议（MCP）服务器，为AI助手提供对Kubernetes集群的深度实时访问。建立在 FastMCP 和那个 Kubernetes操作Python框架（KOPF），它结合了 50个读/写工具 涵盖11个功能类别 背景碰撞循环监视器 检测 OOMKilled, CrashLoopBackOff，并在发生错误的时刻进行错误状态。

将其连接到任何兼容MCP的客户端（Claude Desktop、Cursor、自定义代理），让您的AI副驾驶在不离开对话的情况下观察、诊断和修复Kubernetes问题。

特性

🔴 实时碰撞监控 --KOPF操作员手表 containerStatuses 并发出警报 OOMKilled, CrashLoopBackOff，以及 Error 立即状态。
🛠️ 50个SRE工具 --从集群概述到主动补救，按逻辑类别分组。
🔄 阅读和写入操作 --不仅仅是可观察性：扩展部署、重启工作负载、回滚修订、修补OOM限制、封锁/解除封锁节点。
🧠 令牌优化 -净化API响应（消除类似 managedFields)，压缩YAML序列化，并强制日志截断，以最大限度地提高较小LLM上下文窗口的效用。
📡 MCP本地 --通过以下方式与任何MCP客户端开箱即用 stdio 运输。
🏗️ 模块化架构 --每个工具类别都有自己的模块；易于扩展或定制。

为什么选择KOPF而不是kubectl？

项目如 mcp服务器kubernetes 通过支付费用给人工智能助手Kubernetes访问权限 kubectl 引擎盖下。这是可行的，但它有很大的局限性。 mcp服务器kopf 通过使用 Kubernetes Python客户端 用于API调用和 KOPF 用于实时事件观看。

	基于kubectl的服务器	mcp服务器kopf
API交互	炮弹发射到 `kubectl` → 解析文本输出	原生Python客户端→ 结构化对象
实时监控	❌ 基于民意调查或缺席	✅ KOPF操作员实时观察事件
碰撞检测	手动-必须查询pod	自动-pod崩溃时发出警报
错误处理	CLI输出的字符串解析	来自Kubernetes API的类型异常
依赖	需要 `kubectl` 主机上的二进制文件	没有外部二进制文件——纯Python
补救	仅限于 `kubectl` 谓词	直接API修补程序（缩放、重新启动、回滚、OOM修复）
输出格式	原始CLI文本（易解析）	结构化、一致、专门构建的响应
可扩展性	添加shell命令	添加具有完全API访问权限的Python函数
安全	任意命令执行风险	作用域API调用-无外壳注入表面
闭环SRE	❌ 仅检测和诊断	✅ 检测→ 诊断→ 在一次对话中进行补救

关键优势

🔴 主动，而非被动 --KOPF后台操作员持续监视吊舱状态。存在碰撞警报之前你甚至会问。使用基于kubectl的服务器，AI必须显式运行命令来发现问题。
🔒 无壳，无风险 --基于kubectl的工具执行任意shell命令，这会引入注入风险，并需要安装二进制文件。此服务器仅使用官方Kubernetes Python客户端。
🧱 结构化数据 --而不是解析 kubectl get pods -o wide 文本输出（可以跨版本），每个工具都返回从类型化的API对象构建的干净、结构化的字符串。
⚡ 闭环修复 --除了观察之外，服务器还可以行动：修补程序资源限制、触发器卷展重新启动、回滚部署和警戒节点—所有这些都通过安全的、范围限定的API调用实现。

建筑

┌──────────────────────────────────────────────────────┐
│                    MCP Client                        │
│         (Claude Desktop / Cursor / Agent)            │
└─────────────────────┬────────────────────────────────┘
                      │  stdio (MCP protocol)
┌─────────────────────▼────────────────────────────────┐
│                   main.py                            │
│  ┌──────────────┐  ┌─────────────────────────────┐   │
│  │  FastMCP     │  │  KOPF Background Operator   │   │
│  │  Server      │  │  (Thread)                   │   │
│  │              │  │                             │   │
│  │  45 Tools    │  │  Watches pod status fields  │   │
│  │  registered  │◄─┤  Populates cluster_alerts   │   │
│  └──────────────┘  └─────────────────────────────┘   │
└─────────────────────┬────────────────────────────────┘
                      │  kubernetes python client
┌─────────────────────▼────────────────────────────────┐
│              Kubernetes API Server                   │
└──────────────────────────────────────────────────────┘

工具参考

🖥️ 集群概述

工具	说明
`list_nodes`	列出所有节点的状态、角色、版本、CPU/内存容量
`describe_node`	详细的节点信息：条件、污染、可分配资源、标签
`list_namespaces`	列出所有具有状态和标签的命名空间
`cluster_resource_usage`	总CPU/内存请求与可分配容量

📦 工作量

工具	说明
`list_deployments`	列出具有副本、就绪、可用、年龄的部署
`describe_deployment`	部署细节：策略、条件、容器、标签
`list_statefulsets`	列出带有就绪/所需副本的状态集
`list_daemonsets`	列出具有所需/就绪/可用计数的DaemonSet
`list_replicasets`	列出带有所有者引用的副本集
`list_jobs`	列出工作状态、完成情况、持续时间
`describe_job`	工作细节：完成、并行性、容器、条件
`list_cronjobs`	列出CronJobs及其计划、上次运行、活动计数

🐳 容器组

工具	说明
`list_pods`	列出状态、重启、节点、IP（支持标签选择器）的Pod
`describe_pod`	完整的吊舱细节：条件、容器、体积、事件
`get_pod_logs`	使用容器、尾线和以前的容器支持检索吊舱日志
`get_pod_resource_usage`	通过Metrics API实时使用CPU/内存

🌐 网络

工具	说明
`list_services`	列出服务类型、ClusterIP、外部IP、端口
`describe_service`	带有选择器、端点和端口的服务详细信息
`list_ingresses`	列出带有主机、路径和后端的入口
`list_network_policies`	列出带有选择器和规则计数的网络策略
`list_endpoints`	列出具有就绪/未就绪地址的端点

💾 存储

工具	说明
`list_pvs`	列出持久卷及其容量、访问、回收和状态
`list_pvcs`	列出PVC的状态、容量、绑定量
`describe_pvc`	PVC细节，包括条件和事件
`list_storage_classes`	列出带有配置项、回收策略和参数的StorageClasses

⚙️ 配置

工具	说明
`list_configmaps`	列出带有密钥计数的ConfigMap
`get_configmap`	读取ConfigMap数据（键和值）
`list_secrets`	列出带有类型和密钥计数的机密（隐藏值）
`describe_secret`	显示密钥/大小；可选解码base64值

🔐 基于角色的访问控制

工具	说明
`list_service_accounts`	列出具有秘密计数的服务帐户
`list_roles`	列出具有规则计数的角色
`list_cluster_roles`	列出具有规则计数的ClusterRoles
`list_role_bindings`	列出带有主题和角色参考的角色组合
`list_cluster_role_bindings`	列出带有主题和角色参考的ClusterRole绑定

📈 扩展

工具	说明
`list_hpas`	列出HPA，包括最小/最大/当前副本和CPU目标
`scale_deployment`	手动将部署扩展到N个副本
`scale_statefulset`	手动将StatefulSet扩展到N个副本

🩺 诊断

工具	说明
`generate_cluster_report`	生成整个集群状态的高级报告，包括节点、Pod和警报
`get_diagnostic_context`	为pod或节点收集广泛的上下文以执行根本原因分析
`get_active_alerts`	查看KOPF监视器检测到的实时碰撞警报
`get_recent_events`	检索命名空间中的警告类型事件
`get_all_events`	检索最近发生的所有事件（正常+警告）
`list_resource_quotas`	显示资源配额（使用与硬限制）
`list_limit_ranges`	显示具有默认/最大/最小容器限制的LimitRanges

🔧 补救

工具	说明
`fix_oom_resources`	修补拥有OOMKilled pod的部署的内存限制
`restart_deployment`	执行部署的重新启动
`rollback_deployment`	将部署回滚到上一版本
`cordon_node`	将节点标记为不可调度
`uncordon_node`	再次将节点标记为可调度

🧩 自定义资源

工具	说明
`list_crds`	列出群集中可用的所有自定义资源定义（CRD）
`list_custom_resources`	列出特定CRD的自定义资源
`get_custom_resource`	获取特定自定义资源的完整表示

入门指南

先决条件

Python 3.10+
访问Kubernetes集群（本地或远程）
A有效 kubeconfig 文件或群集服务帐户中
度量服务器已安装（可选--必需 get_pod_resource_usage)

安装

# Clone the repository
git clone https://github.com/your-org/mcp-server-kopf.git
cd mcp-server-kopf

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux / macOS
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install mcp[cli] kopf kubernetes

运行服务器

python main.py

服务器启动于 stdio 模式，准备好任何MCP客户端连接。

配置

Kubernetes上下文

默认情况下，服务器加载 workercluster 本地kubeconfig中的上下文：

config.load_kube_config(context="workercluster")

要使用其他上下文，请编辑 context 参数输入 main.py，或将其完全删除以使用当前默认上下文。在Kubernetes集群内运行时，服务器会自动回退到 load_incluster_config().

MCP客户端配置

将服务器添加到MCP客户端的配置中。例如，在 克劳德桌面 (claude_desktop_config.json):

{
  "mcpServers": {
    "k8s-sre": {
      "command": "python",
      "args": ["/path/to/mcp-server-kopf/main.py"]
    }
  }
}

项目结构

mcp-server-kopf/
├── main.py                 # Entry point — FastMCP server + KOPF crash monitor
├── tools/
│   ├── __init__.py
│   ├── cluster.py          # Nodes, namespaces, cluster resource usage
│   ├── workloads.py        # Deployments, StatefulSets, DaemonSets, Jobs, CronJobs
│   ├── pods.py             # Pod listing, describe, logs, metrics
│   ├── networking.py       # Services, Ingresses, Endpoints, NetworkPolicies
│   ├── storage.py          # PVs, PVCs, StorageClasses
│   ├── config.py           # ConfigMaps, Secrets
│   ├── rbac.py             # Roles, ClusterRoles, Bindings, ServiceAccounts
│   ├── scaling.py          # HPAs, manual scaling
│   ├── diagnostics.py      # Alerts, events, quotas, limit ranges
│   ├── remediation.py      # OOM fix, restart, rollback, cordon/uncordon
│   └── custom_resources.py # CRDs and Custom Resource interactions
├── LICENSE                 # Apache 2.0
└── README.md

碰撞监视器的工作原理

A. KOPF 操作员 在MCP服务器旁边的后台线程中运行。它看着 status.containerStatuses 集群中所有Pod上的字段：

当集装箱进入时 OOMKilled, CrashLoopBackOff，或 Error 状态，操作员捕获警报。
警报存储在共享中 cluster_alerts 字典。
这 get_active_alerts 该工具将这些信息暴露给AI助手。
然后，助理可以进行调查 describe_pod, get_pod_logs，并用 fix_oom_resources, restart_deployment，或 rollback_deployment.

这创建了一个 闭环SRE工作流程：检测→ 诊断→ 补救——所有这些都可以在一次对话中完成。

示例工作流程

You:    "Are there any issues on the cluster?"
AI:     → calls get_active_alerts()
        🚨 Pod payment-svc-7f8b5 in production crashed — OOMKilled

You:    "Show me the logs"
AI:     → calls get_pod_logs("payment-svc-7f8b5", "production", previous=True)
        java.lang.OutOfMemoryError: Java heap space ...

You:    "Increase memory and restart it"
AI:     → calls fix_oom_resources("payment-svc-7f8b5", "production", "1Gi")
        ✅ Deployment 'payment-svc' memory updated to 1Gi
        → calls restart_deployment("payment-svc", "production")
        ✅ Rollout restart initiated

贡献

欢迎投稿！每个工具类别都是一个独立的模块 tools/ --添加新工具：

选择合适的模块（或创建一个新模块）。
在内部定义您的功能 register(mcp) 功能。
用 @mcp.tool().
导入并注册 main.py.

许可证

该项目根据 Apache许可证2.0 --看看许可证文件以获取详细信息。