K8s-Cluster-Operations-MCP-Server

Ein Kubernetes-Operations-Abfrage-MCP-Dienst basierend auf FastMCP. Er kapselt alltägliche Diagnoseaktionen wie kubectl get / describe / logs / events --watch in schreibgeschützte, von LLMs aufrufbare Werkzeuge, sodass Clients wie Claude direkt den Clusterzustand auslesen und die erste Fehlerquelle lokalisieren können.

⚠️ Dieses Projekt exponiert ausschließlich schreibgeschützte Werkzeuge (kein create/update/delete). Dennoch wird empfohlen, die RBAC mit einem schreibgeschützten ServiceAccount zu kombinieren – siehe „Sicherheitsempfehlungen" weiter unten.

Werkzeugübersicht

Zusätzlich gibt es die beiden ergänzenden Fähigkeiten @mcp.prompt (Knoten-Diagnose / Cluster-Inspektionsführung) und @mcp.resource (k8s://cluster/summary – Cluster-Zusammenfassung).

Related MCP server: k8s-readonly-mcp

Verzeichnisstruktur

├── app.py              # FastMCP 实例（叶子模块，破循环导入）
├── k8s_server.py       # 入口：导入 Tools 即自动注册全部工具
├── k8s_client.py       # K8s 客户端懒加载 + 单一配置真源
├── config.py           # 12-Factor 环境变量配置
├── prompts.py          # @mcp.prompt 引导
├── resources.py        # @mcp.resource 资源
├── Tools/              # 每个工具一个文件，导入即注册
├── utils/              # 纯解析/辅助模块（无 K8s/MCP 依赖）
└── tests/              # 单元测试

Installation und Ausführung

# 1. 创建虚拟环境并安装依赖
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

# 2. 运行（HTTP transport，默认 127.0.0.1:8081）
python k8s_server.py

Ausführen der Tests

pip install -r requirements-dev.txt
python -m pytest -q

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen mit Standardwerten (siehe config.py):

Ladepriorität der K8s-Verbindungskonfiguration: In-Cluster (Pod-ServiceAccount) → expliziter KUBECONFIG_PATH → offizielle kubeconfig-Auflösungskette – es wird stets eine einzige Quelle verwendet, keine Zusammenführung mehrerer Dateien.

Anbindung an MCP-Clients

Am Beispiel von Claude Code (bei bereits laufendem HTTP-Transport auf 127.0.0.1:8081):

{
  "mcpServers": {
    "k8s-node-server": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

Sicherheitsempfehlungen

1. Schreibgeschützte RBAC verwenden: Konfigurieren Sie für den Pod / Benutzer, der diesen Dienst ausführt, eine schreibgeschützte ClusterRole – vermeiden Sie die Verwendung von Konten mit hohen Berechtigungen.

2. Standardmäßig nur lokal binden: MCP_HOST ist standardmäßig 127.0.0.1. Falls eine externe Erreichbarkeit erforderlich ist, muss zwingend eine Authentifizierung auf der Reverse-Proxy-Ebene ergänzt werden (TLS + Token / OIDC), da der HTTP-Transport selbst keine Authentifizierung und keine Ratenbegrenzung bietet.

3. Zertifikatsprüfung nicht deaktivieren: K8S_VERIFY_SSL=false ist ausschließlich für die temporäre Fehlersuche mit selbstsignierten Zertifikaten gedacht; in Produktionsumgebungen muss der Wert true bleiben.

4. Keine Anmeldeinformationen ins Repository: Die kubeconfig enthält Schlüssel; .gitignore schließt kubeconfig* bereits aus – erzwingen Sie kein versehentliches Einchecken.

Bekannte Grenzen

• Alle Werkzeuge sind schreibgeschützt und enthalten keine Änderungsoperationen (bewusste Designentscheidung).

• Die watch_*-Serie unterliegt einer globalen Sperre: Es kann immer nur ein Watch gleichzeitig aktiv sein, um den API-Server nicht zusätzlich zu belasten.

• Ereignis-/Log-Ausgaben haben eine Längenbegrenzung; sehr große Inhalte werden abgeschnitten (siehe Abschneide-Logik in read_pod_log sowie max_count in query_events).