MCP Kubernetes Ro

🚀 Kubernetes只讀MCP服務器

mcp-kubernetes-ro是一個模型上下文協議（MCP）服務器，為AI助手提供對Kubernetes集群的只讀訪問。它使AI模型能夠列出資源、獲取資源詳細信息、檢索Pod日誌、發現API資源以及執行Base64編碼/解碼操作，同時通過只讀訪問確保安全性。

該服務器利用你本地的kubectl配置（即使不需要安裝kubectl），併為你的Kubernetes集群提供一個安全的只讀接口，防止任何破壞性操作，同時允許進行全面的集群檢查和故障排除。

🚀 快速開始

mcp-kubernetes-ro服務器可助力AI助手安全地對Kubernetes集群開展只讀操作。要使用該服務器，你可按需挑選合適的安裝與配置方式。

✨ 主要特性

• 無需安裝kubectl：MCP服務器藉助你本地的kubectl配置來連接Kubernetes集群，而非依賴kubectl二進制文件，因此即便你的機器上未安裝kubectl，它也能正常工作。
• 資源列表：可按資源類型列出任意Kubernetes資源，並可通過標籤、字段和命名空間進行篩選。
• 資源詳情：獲取特定Kubernetes資源的完整詳細信息。
• Pod日誌：支持高級篩選選項，如grep模式、時間過濾和獲取先前日誌，從而檢索Pod日誌。
• 容器發現：列出Pod內的容器，便於有針對性地訪問日誌。
• API發現：發現可用的Kubernetes API資源及其功能。
• Base64工具：對Kubernetes的秘密和配置進行Base64數據的編碼和解碼。
• 多種傳輸模式：支持標準輸入輸出（stdio）和服務器發送事件（SSE）兩種通信方式。
• 只讀安全：在保持全面檢查能力的同時，完全防止破壞性操作。
• 命名空間支持：可處理特定命名空間或集群範圍的資源。
• 高級過濾：支持標籤選擇器、字段選擇器和分頁功能。
• 單命令上下文：為單個命令指定不同的Kubernetes上下文。
• 環境變量支持：自動檢測KUBECONFIG環境變量。
• 啟動連接檢查：在啟動時自動驗證集群連接和基本權限。

📦 安裝指南

你可以從發佈頁面獲取預構建的二進制文件。

或者，你也可以使用macOS或Linux上的Homebrew進行安裝：

brew install patrickdappollonio/tap/mcp-kubernetes-ro

你還可以將其作為NPM包使用，只需確保將配置提供給你的AI代理：

npx -y @patrickdappollonio/mcp-kubernetes-ro

最後，Docker用戶可以從GitHub容器註冊表中獲取預構建的鏡像：

docker pull ghcr.io/patrickdappollonio/mcp-kubernetes-ro:latest

編輯器配置

將以下配置添加到你的編輯器設置中，以使用mcp-kubernetes-ro：

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "mcp-kubernetes-ro",
      "args": [
        // 按需取消註釋並修改：
        // "--kubeconfig=/path/to/kubeconfig",
        // "--namespace=default",
        // "--transport=stdio",
        // "--port=8080",
        // "--disabled-tools=get_logs,decode_base64"
      ],
      "env": {
        // 按需設置KUBECONFIG環境變量：
        // "KUBECONFIG": "/path/to/kubeconfig",
        // 按需設置MCP_KUBERNETES_RO_DISABLED_TOOLS環境變量：
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // 或者使用通用的DISABLED_TOOLS環境變量：
        // "DISABLED_TOOLS": "get_logs,decode_base64"
      }
    }
  }
}

你可以像上面那樣直接從$PATH中使用mcp-kubernetes-ro，也可以提供二進制文件的完整路徑（例如/path/to/mcp-kubernetes-ro）。

你還可以通過將其作為npx包使用來簡化安裝過程：

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "npx",
      "args": [
        "-y",
        "@patrickdappollonio/mcp-kubernetes-ro"
        // 按需取消註釋並修改：
        // "--kubeconfig=/path/to/kubeconfig",
        // "--namespace=default",
        // "--transport=stdio",
        // "--port=8080",
        // "--disabled-tools=get_logs,decode_base64"
      ],
      "env": {
        // 按需設置KUBECONFIG環境變量：
        // "KUBECONFIG": "/path/to/kubeconfig",
        // 按需設置MCP_KUBERNETES_RO_DISABLED_TOOLS環境變量：
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // 或者使用通用的DISABLED_TOOLS環境變量：
        // "DISABLED_TOOLS": "get_logs,decode_base64"
      }
    }
  }
}

以下是如何使用Docker鏡像的配置：

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "KUBECONFIG=/root/.kube/config",
        "-v", "/path/to/kubeconfig:/root/.kube/config",
        "ghcr.io/patrickdappollonio/mcp-kubernetes-ro"
        // 在此處添加其他標誌，如--disabled-tools=get_logs,decode_base64
      ],
      "env": {
        // 按需設置KUBECONFIG環境變量：
        // "KUBECONFIG": "/path/to/kubeconfig",
        // 按需設置MCP_KUBERNETES_RO_DISABLED_TOOLS環境變量：
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // 或者使用通用的DISABLED_TOOLS環境變量：
        // "DISABLED_TOOLS": "get_logs,decode_base64"
      }
    },
  }
}

請注意，你需要將你的kubeconfig文件掛載到容器中，並將KUBECONFIG環境變量設置為掛載文件的路徑，或者使用--kubeconfig標誌進行設置。

前提條件

• 有效的Kubernetes配置文件（通常為~/.kube/config）。
• 有效的憑證和集群訪問權限（不需要kubectl二進制文件）。
• 進行讀操作所需的適當RBAC權限。
• 指標服務器（指標工具所需）：對於指標功能（get_node_metrics、get_pod_metrics），你的集群中必須安裝指標服務器。如果不可用，這些工具將返回錯誤消息。

💻 使用示例

基礎用法

# 使用默認kubeconfig和上下文啟動
mcp-kubernetes-ro

# 使用特定的kubeconfig啟動
mcp-kubernetes-ro --kubeconfig ~/.kube/config

# 使用KUBECONFIG環境變量啟動
export KUBECONFIG=~/.kube/config
mcp-kubernetes-ro

# 使用特定的命名空間啟動
mcp-kubernetes-ro --namespace kube-system

# 以SSE模式啟動
mcp-kubernetes-ro --transport=sse --port=3000

高級用法

# 使用特定kubeconfig的生產集群
mcp-kubernetes-ro \
  --kubeconfig ~/.kube/prod-config \
  --namespace monitoring

# 使用環境變量以SSE模式進行開發設置
export KUBECONFIG=~/.kube/dev-config
mcp-kubernetes-ro \
  --transport=sse \
  --port=8080

# 使用單命令上下文（在工具調用中指定上下文）
# 現在上下文在工具級別指定，而非全局指定

# 出於安全或性能原因禁用特定工具
mcp-kubernetes-ro --disabled-tools=get_logs,decode_base64

# 當指標服務器不可用時禁用指標工具
mcp-kubernetes-ro --disabled-tools=get_node_metrics,get_pod_metrics

# 在生產環境中禁用多個工具
mcp-kubernetes-ro \
  --kubeconfig ~/.kube/prod-config \
  --disabled-tools=encode_base64,decode_base64,get_logs

# 使用特定於應用的環境變量禁用工具
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs,decode_base64
mcp-kubernetes-ro

# 使用通用環境變量禁用工具
export DISABLED_TOOLS=get_logs,decode_base64
mcp-kubernetes-ro

# 命令行標誌優先於兩個環境變量
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs,decode_base64
export DISABLED_TOOLS=get_pod_metrics
mcp-kubernetes-ro --disabled-tools=get_node_metrics,get_pod_metrics

📚 詳細文檔

可用的MCP工具

共有10個工具可用：

• list_resources：按資源類型列出任意Kubernetes資源，並可進行可選過濾，結果按最新優先排序。
• get_resource：獲取特定資源的詳細信息。
• get_logs：獲取Pod日誌，支持高級過濾選項，如grep模式、時間過濾和獲取先前日誌。
• get_pod_containers：列出Pod內的容器，以便訪問日誌。
• list_api_resources：列出可用的Kubernetes API資源及其詳細信息（類似於kubectl api-resources）。
• list_contexts：從kubeconfig文件中列出可用的Kubernetes上下文。
• get_node_metrics：獲取節點指標（CPU和內存使用情況）。
• get_pod_metrics：獲取Pod指標（CPU和內存使用情況）。
• encode_base64：將文本數據編碼為Base64格式。
• decode_base64：將Base64數據解碼為文本格式。

工具管理

禁用工具

你可以使用--disabled-tools命令行標誌或環境變量來禁用特定工具，工具名稱使用逗號分隔。支持兩個環境變量以適應不同的使用場景：

• MCP_KUBERNETES_RO_DISABLED_TOOLS：特定於應用的變量，不會與其他工具衝突。
• DISABLED_TOOLS：通用變量，可在你的環境中的多個工具之間共享。

優先級順序：

1. 命令行標誌：--disabled-tools=NAMES（優先級最高）。
2. 特定於應用的環境變量：MCP_KUBERNETES_RO_DISABLED_TOOLS。
3. 通用環境變量：DISABLED_TOOLS。

這在以下情況很有用：

• 安全：禁用可能暴露敏感信息的工具（例如get_logs、decode_base64）。
• 性能：在不需要時禁用資源密集型工具（例如get_node_metrics、get_pod_metrics）。
• 特定環境：禁用在你的集群中不可用的工具（例如當指標服務器未安裝時的指標工具）。
• 合規性：限制功能以滿足組織政策。

可禁用的工具名稱：

• list_resources
• get_resource
• get_logs
• get_pod_containers
• list_api_resources
• list_contexts
• get_node_metrics
• get_pod_metrics
• encode_base64
• decode_base64

當一個工具被禁用時，它將不會在MCP服務器中註冊，並且不會出現在可用工具列表中。一條消息將記錄到標準錯誤輸出，指示哪些工具已被跳過。

示例：

# 使用命令行標誌（優先級最高）
mcp-kubernetes-ro --disabled-tools=encode_base64,decode_base64,get_logs

# 使用特定於應用的環境變量
export MCP_KUBERNETES_RO_DISABLED_TOOLS=encode_base64,decode_base64,get_logs
mcp-kubernetes-ro

# 使用通用環境變量
export DISABLED_TOOLS=encode_base64,decode_base64,get_logs
mcp-kubernetes-ro

# 優先級演示：命令行標誌覆蓋環境變量
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs
export DISABLED_TOOLS=get_pod_metrics
mcp-kubernetes-ro --disabled-tools=encode_base64,decode_base64

# 優先級演示：特定於應用的環境變量覆蓋通用環境變量
export MCP_KUBERNETES_RO_DISABLED_TOOLS=encode_base64,decode_base64
export DISABLED_TOOLS=get_logs,get_pod_metrics
mcp-kubernetes-ro

# 輸出：Skipping disabled tool: "encode_base64"
# 輸出：Skipping disabled tool: "decode_base64"

運行模式

標準（stdio）模式

默認情況下，mcp-kubernetes-ro以stdio模式運行，適用於與通過標準輸入/輸出進行通信的編輯器和其他工具集成。

mcp-kubernetes-ro

服務器發送事件（SSE）模式

或者，你可以將mcp-kubernetes-ro作為支持SSE的HTTP服務器運行，用於基於Web的集成：

mcp-kubernetes-ro --transport=sse --port=8080

在SSE模式下，服務器將監聽指定的端口（默認：8080），並通過HTTP使用服務器發送事件提供相同的MCP工具。這對於Web應用程序或不適合使用stdio通信的環境很有用。

配置選項

以下命令行標誌可用於配置MCP服務器：

Kubernetes配置

• --kubeconfig=PATH：kubeconfig文件的路徑（默認為KUBECONFIG環境變量，然後是~/.kube/config）。
• --namespace=NAME：操作的默認命名空間（默認為當前命名空間）。

傳輸選項

• --transport=TYPE：傳輸類型：stdio或sse（默認：stdio）。
• --port=PORT：SSE服務器的端口（默認：8080，僅在--transport=sse時使用）。

工具管理

• --disabled-tools=NAMES：要禁用的工具名稱列表，使用逗號分隔（可選）。
• MCP_KUBERNETES_RO_DISABLED_TOOLS：特定於應用的環境變量，用於禁用工具（命令行標誌優先）。
• DISABLED_TOOLS：通用環境變量，用於禁用工具（優先級低於MCP_KUBERNETES_RO_DISABLED_TOOLS）。

上下文配置

服務器支持單命令上下文。這在使用同一$KUBECONFIG文件中的多個Kubernetes集群或上下文時提供了更大的靈活性。

配置優先級：

1. 命令級上下文：在單個工具調用中使用context參數。
2. Kubeconfig默認值：使用kubeconfig文件中指定的當前上下文。

Kubeconfig解析優先級：

1. 命令行標誌：--kubeconfig參數。
2. 環境變量：KUBECONFIG環境變量。
3. 默認路徑：~/.kube/config。
4. 集群內配置：在Kubernetes Pod內運行時自動檢測。

示例：

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production-cluster"
}

這種方法允許你：

• 在同一會話中為不同操作使用不同的上下文。
• 無需重啟服務器即可按命令切換上下文。
• 與現有的kubeconfig設置保持兼容。

工具使用文檔

列出資源

按資源類型列出任意Kubernetes資源，並可進行可選過濾，結果按最新優先排序。

參數：

• resource_type（必需）：要列出的資源類型 - 使用複數形式（例如'pods'、'deployments'、'services'）。
• api_version（可選）：資源的API版本（例如'v1'、'apps/v1'）。
• namespace（可選）：目標命名空間（為空則表示集群範圍的資源）。
• context（可選）：要使用的Kubernetes上下文（默認為kubeconfig中的當前上下文）。
• label_selector（可選）：用於過濾資源的標籤選擇器（例如'app=nginx,version=1.0'）。
• field_selector（可選）：用於過濾資源的字段選擇器（例如'status.phase=Running'）。
• limit（可選）：要返回的最大資源數量（默認為所有）。
• continue（可選）：用於分頁的繼續令牌（來自上一個響應）。

示例：

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production",
  "label_selector": "app=nginx"
}

獲取資源

獲取特定資源的詳細信息和完整配置。

參數：

• resource_type（必需）：要獲取的資源類型。
• name（必需）：資源名稱。
• api_version（可選）：資源的API版本（例如'v1'、'apps/v1'）。
• namespace（可選）：目標命名空間（對於命名空間資源是必需的）。
• context（可選）：要使用的Kubernetes上下文（默認為kubeconfig中的當前上下文）。

示例：

{
  "resource_type": "deployment",
  "name": "nginx-deployment",
  "namespace": "default",
  "context": "production"
}

獲取日誌

獲取Pod日誌，支持高級過濾選項，如grep模式、時間過濾和獲取先前日誌。

參數：

• namespace（必需）：Pod所在的命名空間。
• name（必需）：Pod名稱。
• container（可選）：容器名稱（對於多容器Pod是必需的）。
• context（可選）：要使用的Kubernetes上下文（默認為kubeconfig中的當前上下文）。
• max_lines（可選）：要檢索的最大行數。
• grep_include（可選）：僅包含匹配這些模式的行（使用逗號分隔）。類似於grep - 包含包含任何這些模式的行。
• grep_exclude（可選）：排除匹配這些模式的行（使用逗號分隔）。類似於grep -v - 排除包含任何這些模式的行。
• use_regex（可選）：是否將grep模式視為正則表達式而不是字面字符串。
• since（可選）：返回比此時間更新的日誌。支持持續時間，如"5m"、"1h"、"2h30m"、"1d"或絕對時間，如"2023-01-01T10:00:00Z"。
• previous（可選）：返回上一個終止的容器實例的日誌（類似於kubectl logs --previous）。

示例：

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "container": "nginx",
  "context": "production",
  "max_lines": "100",
  "grep_include": "error,warning",
  "since": "5m"
}

獲取Pod容器

列出Pod內的容器，以便訪問日誌。

參數：

• namespace（必需）：Pod所在的命名空間。
• name（必需）：Pod名稱。
• context（可選）：要使用的Kubernetes上下文（默認為kubeconfig中的當前上下文）。

示例：

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "context": "production"
}

列出API資源

列出可用的Kubernetes API資源及其詳細信息（類似於kubectl api-resources）。

參數：無

示例：

{}

列出上下文

從kubeconfig文件中列出可用的Kubernetes上下文。這對於發現其他工具中context參數可用的上下文很有用。

參數：無

示例：

{}

示例響應：

{
  "contexts": [
    {
      "name": "production",
      "cluster": "prod-cluster",
      "user": "prod-user",
      "namespace": "default",
      "current": true
    },
    {
      "name": "staging",
      "cluster": "staging-cluster",
      "user": "staging-user",
      "namespace": "staging",
      "current": false
    }
  ],
  "count": 2
}

獲取節點指標

從指標服務器獲取節點指標（CPU和內存使用情況）。結果按時間戳排序（最新優先），以確保一致的排序和分頁，因為內置的指標服務器端點不支持基於指針的分頁。

參數：

• node_name（可選）：要獲取指標的特定節點名稱。如果未提供，則返回所有節點的指標。
• context（可選）：要使用的Kubernetes上下文（默認為kubeconfig中的當前上下文）。
• limit（可選）：要返回的最大節點指標數量。如果未提供，則返回所有可用指標。
• continue（可選）：用於分頁的繼續令牌（來自上一個響應）。

錯誤處理：

• 如果指標服務器不可用，則返回錯誤消息。
• 檢測常見的指標服務器錯誤並提供具體指導。

示例：

{
  "node_name": "worker-node-1",
  "context": "production",
  "limit": 5
}

示例響應（單個節點）：

{
  "kind": "NodeMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "worker-node-1",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "10.062s",
  "usage": {
    "cpu": "137m",
    "memory": "1368128Ki"
  }
}

示例響應（帶分頁的列表）：

{
  "kind": "NodeMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "count": 5,
  "items": [
    {
      "kind": "NodeMetrics",
      "metadata": { "name": "node-1" },
      "timestamp": "2023-01-01T12:00:00Z",
      "usage": { "cpu": "137m", "memory": "1368128Ki" }
    }
  ],
  "continue": "eyJvZmZzZXQiOjUsInR5cGUiOiJub2RlIiwibmFtZXNwYWNlIjoiIn0="
}

獲取Pod指標

從指標服務器獲取Pod指標（CPU和內存使用情況）。結果按時間戳排序（最新優先），以確保一致的排序和分頁，因為內置的指標服務器端點不支持基於指針的分頁。

參數：

• namespace（可選）：要獲取Pod指標的命名空間。如果未提供，則返回所有命名空間中所有Pod的指標。
• pod_name（可選）：要獲取指標的特定Pod名稱。如果指定，則需要namespace。
• context（可選）：要使用的Kubernetes上下文（默認為kubeconfig中的當前上下文）。
• limit（可選）：要返回的最大Pod指標數量。如果未提供，則返回所有可用指標。
• continue（可選）：用於分頁的繼續令牌（來自上一個響應）。

錯誤處理：

• 如果指標服務器不可用，則返回錯誤消息。
• 檢測常見的指標服務器錯誤並提供具體指導。
• 驗證在指定pod_name時提供了namespace。

分頁注意事項：

• 繼續令牌是上下文感知的，如果命名空間上下文發生變化則會重置。
• 實現了客戶端分頁，以確保一致的排序和過濾。

示例（特定Pod）：

{
  "namespace": "kube-system",
  "pod_name": "metrics-server-557ff575fb-9dcl4",
  "context": "production"
}

示例（帶分頁）：

{
  "namespace": "kube-system",
  "context": "production",
  "limit": 10,
  "continue": "eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

示例響應（單個Pod）：

{
  "kind": "PodMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "metrics-server-557ff575fb-9dcl4",
    "namespace": "kube-system",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "18.888s",
  "containers": [
    {
      "name": "metrics-server",
      "usage": {
        "cpu": "8020419n",
        "memory": "48164Ki"
      }
    }
  ]
}

示例響應（帶分頁的列表）：

{
  "kind": "PodMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "namespace": "kube-system",
  "count": 10,
  "items": [
    {
      "kind": "PodMetrics",
      "metadata": { "name": "pod-1", "namespace": "kube-system" },
      "timestamp": "2023-01-01T12:00:00Z",
      "containers": [
        {
          "name": "container-1",
          "usage": { "cpu": "8020419n", "memory": "48164Ki" }
        }
      ]
    }
  ],
  "continue": "eyJvZmZzZXQiOjIwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

編碼Base64

將文本數據編碼為Base64格式。

參數：

• data（必需）：要編碼的文本數據。

示例：

{
  "data": "username:password"
}

解碼Base64

將Base64數據解碼為文本格式。

參數：

• data（必需）：要解碼的Base64數據。

示例：

{
  "data": "dXNlcm5hbWU6cGFzc3dvcmQ="
}

🔧 技術細節

指標實現細節

錯誤檢測和處理

指標工具（get_node_metrics和get_pod_metrics）包含對指標服務器可用性的複雜錯誤檢測：

• 自動檢測：檢測指標服務器是否未安裝或無響應。
• 有用的錯誤消息：在指標服務器缺失時提供具體的安裝命令。
• 常見錯誤模式：識別各種指標服務器錯誤場景：
  • 未找到metrics-server服務。
  • metrics.k8s.io API組不可用。
  • “服務器找不到請求的資源”錯誤。
  • “沒有可用的指標”情況。

分頁實現

由於內置的指標服務器端點不支持基於指針的分頁，兩個指標工具都實現了客戶端分頁，以確保結果一致，同時為AI工具提供一種安全的方式來請求所需的數據，特別是在小上下文窗口中。

• 排序：所有結果在分頁前按時間戳排序（最新優先）。
• 繼續令牌：Base64編碼的JSON令牌包含：
  • offset：結果集中的當前位置。
  • type：資源類型（“node”或“pod”）。
  • namespace：上下文命名空間（對於Pod指標）。
• 上下文感知：當命名空間上下文發生變化時，分頁狀態重置。
• 令牌格式：eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ==

資源檢索策略

• 先獲取再過濾：始終從服務器檢索所有可用指標，然後應用客戶端過濾和分頁。
• 一致排序：確保跨分頁請求的可預測結果。
• 命名空間範圍：當提供時，自動將Pod指標範圍限定到特定命名空間。

錯誤處理

服務器為常見問題提供詳細的錯誤消息：

• 無效的資源類型或API版本。
• 缺少必需的參數。
• RBAC權限錯誤。
• 網絡連接問題。
• 格式錯誤的kubeconfig文件。
• 指標服務器不可用（提供安裝指導）。

📄 許可證

文檔中未提及相關信息，故跳過該章節。

使用場景

集群故障排除

• 跨命名空間列出失敗的Pod。
• 獲取詳細的資源配置。
• 檢索Pod日誌進行調試。
• 發現可用的API資源。

資源發現

• 按類型探索集群資源。
• 查找具有特定標籤的資源。
• 理解資源關係。
• 識別資源配置。

安全與合規

• 只讀訪問防止意外更改。
• 檢查配置而無修改風險。
• 審計資源狀態和設置。
• 安全地探索生產集群。

AI輔助操作

• 讓AI助手幫助診斷集群問題。
• 獲取資源問題的智能建議。
• 自動日誌分析和模式識別。
• 對Kubernetes資源進行自然語言查詢。

AI助手注意事項

雖然此MCP服務器為Kubernetes集群檢查提供了全面的工具，但一些AI助手可能存在限制或策略，即使技術上可用，也會阻止它們使用某些工具組合。

潛在限制

• 秘密訪問：由於處理憑據的安全策略，一些AI助手可能拒絕檢索、解碼或顯示Kubernetes秘密（即使使用提供的get_resource和decode_base64工具）。
• 敏感數據：無論用戶權限或工具可用性如何，AI模型可能內置了在聊天界面中不暴露敏感信息的限制。
• 安全模式：某些AI助手優先考慮安全最佳實踐而非技術能力，可能拒絕可能暴露敏感數據的操作。

解決方法

如果你的AI助手因安全原因拒絕使用可用工具：

1. 直接CLI訪問：直接使用kubectl進行敏感操作，並讓AI提供要運行的命令，例如：

kubectl get secret <secret-name> -n <namespace> -o yaml
echo "<base64-data>" | base64 -d

2. 手動工具使用：如果以編程方式使用MCP服務器，請直接調用工具，而不是通過AI助手。
3. 文檔：考慮安全影響 - AI的拒絕可能實際上是在保護你免受意外的憑據暴露。

設計理念

這種行為反映了不同的安全方法：

• 基於工具：如果你擁有工具和權限，就應該能夠使用它們。
• AI安全：優先考慮防止意外暴露，而非技術能力。 兩種觀點都是有效的，在設計涉及敏感數據檢索的工作流程時應考慮這一限制。

啟動連接檢查

MCP服務器在啟動時會自動執行連接檢查，以驗證它是否能夠成功連接到你的Kubernetes集群。此檢查包括：

1. API服務器可達性：驗證Kubernetes API服務器是否可訪問並響應。
2. 身份驗證：確認你的憑據有效並被集群接受。
3. API發現：測試服務器是否能夠發現可用的API資源。
4. 基本權限：驗證你至少具有對命名空間的讀訪問權限（基本RBAC檢查）。

你將看到的內容

啟動成功時，你將看到如下輸出：

Testing connectivity to Kubernetes cluster...
✓ Successfully connected to Kubernetes cluster (version: v1.28.0, 4 namespaces accessible)

連接問題排查

如果連接檢查失敗，你將看到詳細的錯誤消息。常見問題包括：

• 無效的kubeconfig：檢查你的kubeconfig文件是否存在且格式正確。
• 集群不可達：驗證集群端點是否可從你的網絡訪問。
• 身份驗證失敗：確保你的憑據未過期且有效。
• 權限不足：驗證你至少具有對基本集群資源的讀訪問權限。 連接檢查有30秒的超時時間，以防止在無響應的集群上掛起。

安全考慮

• 只讀訪問：服務器僅支持讀操作（get、list、watch）。
• 本地身份驗證：使用你現有的kubectl配置和憑據。
• 無破壞性操作：無法創建、更新或刪除資源。
• 命名空間隔離：遵循kubeconfig中的RBAC權限。
• 安全通信：支持標準輸入輸出和基於HTTPS的SSE通信。

侷限性

• 需要本地kubectl配置。
• 僅支持只讀訪問（無寫操作）。
• 僅限於你的kubeconfig憑據可訪問的資源。
• 不支持日誌的即時流式傳輸（僅靜態檢索）。
• 除API資源外，不支持自定義資源定義的發現。