MCP Server Kubog

⚙️ mcp-server-kubog

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

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

______________________________________________________________________

概述

将其连接到任何兼容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 用于实时事件观看。

关键优势

• 🔴 主动，而非被动 --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                   │
└──────────────────────────────────────────────────────┘

______________________________________________________________________

工具参考

🖥️ 集群概述

📦 工作量

🐳 容器组

🌐 网络

💾 存储

⚙️ 配置

🔐 基于角色的访问控制

📈 扩展

🩺 诊断

🔧 补救

🧩 自定义资源

______________________________________________________________________

入门指南

先决条件

• 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上的字段：

1. 当集装箱进入时 OOMKilled, CrashLoopBackOff，或 Error 状态，操作员捕获警报。
2. 警报存储在共享中 cluster_alerts 字典。
3. 这 get_active_alerts 该工具将这些信息暴露给AI助手。
4. 然后，助理可以进行调查 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/ --添加新工具：

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

______________________________________________________________________

许可证

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