Kubernetes MCP

🚀 Kubernetes MCP Server

Kubernetes MCP Server 是一個模型上下文協議（MCP）服務器，它為調試和檢查提供了對 Kubernetes 資源的安全、只讀訪問。該服務器在設計時充分考慮了安全性，可在不具備修改功能的情況下，提供全面的集群可見性。

https://github.com/user-attachments/assets/89df70b0-65d1-461c-b4ab-84b2087136fa

🚀 快速開始

前提條件

• 擁有有效的 kubeconfig 文件，以訪問 Kubernetes 集群。
• 安裝 Go 1.24 或更高版本（用於從源代碼構建）。

安裝選項

選項 1：使用 Go 安裝（推薦）

go install github.com/kkb0318/kubernetes-mcp@latest

安裝完成後，二進制文件將位於 $GOPATH/bin/kubernetes-mcp （若未設置 GOPATH，則位於 $HOME/go/bin/kubernetes-mcp）。

選項 2：從源代碼構建

git clone https://github.com/kkb0318/kubernetes-mcp.git
cd kubernetes-mcp
go build -o kubernetes-mcp .

✨ 主要特性

• 🔒 只讀安全：可安全地檢查 Kubernetes 資源，且不具備修改功能。
• 🎯 支持自定義資源定義（CRD）：可與集群中的任何自定義資源定義無縫協作。
• 🌐 多集群支持：可在不同的 Kubernetes 上下文之間無縫切換。
• 🔍 智能發現：可通過 API 組子字符串查找資源（例如，使用 "flux" 查找 FluxCD 資源，使用 "argo" 查找 ArgoCD 資源）。
• ⚡ 高性能：通過過濾和分頁實現高效的資源查詢。
• 🛠️ 綜合工具集：
  • list_resources：使用高級選項列出並過濾 Kubernetes 資源。
  • describe_resource：獲取特定資源的詳細信息。
  • get_pod_logs：使用複雜的過濾功能檢索 Pod 日誌。
  • list_events：列出並過濾 Kubernetes 事件，用於調試和監控。
  • list_contexts：從 kubeconfig 文件中列出所有可用的 Kubernetes 上下文。

📦 安裝指南

MCP 服務器設置

將服務器添加到 MCP 配置中：

基本配置

自動使用 ~/.kube/config：

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kubernetes-mcp"
    }
  }
}

自定義 kubeconfig

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kubernetes-mcp",
      "env": {
        "KUBECONFIG": "/path/to/your/kubeconfig"
      }
    }
  }
}

⚠️ 重要提示

請將 /path/to/kubernetes-mcp 替換為實際的二進制文件路徑。

獨立使用

# 使用默認 kubeconfig (~/.kube/config)
./kubernetes-mcp

# 使用自定義 kubeconfig 路徑
KUBECONFIG=/path/to/your/kubeconfig ./kubernetes-mcp

⚠️ 重要提示

請確保對要檢查的 Kubernetes 資源具有適當的讀取權限。

💻 使用示例

list_resources

使用高級功能列出並過濾 Kubernetes 資源。

示例：

// 列出帶有標籤選擇器的 Pod
{
  "kind": "Pod",
  "namespace": "default",
  "labelSelector": "app=nginx"
}

// 列出特定集群上下文中的 Pod
{
  "kind": "Pod",
  "context": "production-cluster",
  "namespace": "default"
}

// 發現 FluxCD 資源
{
  "kind": "all",
  "groupFilter": "flux"
}

describe_resource

獲取特定 Kubernetes 資源的詳細信息。

示例：

{
  "kind": "Pod",
  "name": "nginx-pod",
  "namespace": "default"
}

get_pod_logs

使用複雜的過濾選項檢索 Pod 日誌。

示例：

{
  "name": "nginx-pod",
  "namespace": "default",
  "tail": 50,
  "since": "5m",
  "timestamps": true
}

list_events

使用高級過濾選項列出並過濾 Kubernetes 事件，用於調試和監控。

示例：

// 列出最近的警告事件
{
  "eventType": "Warning",
  "since": "30m"
}

// 列出特定 Pod 的事件
{
  "object": "nginx-pod",
  "namespace": "default"
}

// 列出調度失敗的事件
{
  "reason": "FailedScheduling",
  "limit": 50
}

list_contexts

從 kubeconfig 文件中列出所有可用的 Kubernetes 上下文。

參數： 無 - 此工具不接受任何參數。

示例響應：

{
  "contexts": [
    {
      "name": "production-cluster",
      "is_current": false
    },
    {
      "name": "staging-cluster", 
      "is_current": true
    },
    {
      "name": "development-cluster",
      "is_current": false
    }
  ],
  "current_context": "staging-cluster",
  "total": 3
}

用例： 非常適合多集群工作流，您可以：

• 發現可用的 Kubernetes 上下文。
• 識別當前活動的上下文。
• 規劃跨多個集群的操作。

🌟 高級特性

🌐 多集群支持

通過上下文切換，可無縫地與多個 Kubernetes 集群協作：

• 上下文參數：所有工具現在都支持可選的 context 參數，用於指定要查詢的集群。
• 自動發現：使用現有的 kubeconfig 文件，並自動發現可用的上下文。
• 默認上下文：如果未指定上下文，則使用 kubeconfig 中的當前上下文。
• 緩存連接：通過連接緩存有效地管理與多個集群的連接。

多集群示例：

// 查詢生產集群
{
  "kind": "Pod",
  "context": "production-cluster",
  "namespace": "default"
}

// 獲取暫存環境中的 Pod 日誌
{
  "name": "api-server",
  "context": "staging-cluster",
  "namespace": "api"
}

// 跨環境比較資源（使用多次調用）
{
  "kind": "Deployment",
  "context": "production-cluster",
  "namespace": "app"
}

🎯 自定義資源定義（CRD）支持

可自動發現並與集群中的任何 CRD 協作。只需在 list_resources 或 describe_resource 工具中使用 CRD 的 Kind 名稱即可。

🔍 智能資源發現

使用 groupFilter 參數按 API 組子字符串發現資源：

🔒 安全與保障

該服務器在設計時將安全作為首要考慮因素：

• ✅ 只讀訪問 - 無法創建、修改或刪除資源。
• ✅ 適合生產環境 - 可安全地在生產環境中使用。
• ✅ 最小權限 - 僅需要對集群資源的讀取權限。
• ✅ 無破壞性操作 - 不會對集群造成損害。

🤝 貢獻

我們歡迎貢獻！請確保所有更改都保持服務器的只讀性質，幷包含適當的測試。

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。