Kubernetes MCP Server

疑難排解失敗的資源 — 請助理檢查單一資源的狀態、事件、相關物件和部署歷史，找出失敗原因。
列出命名空間和資源 — 請助理列舉叢集的命名空間，或列出指定種類的資源，並為每個資源提供一行狀態摘要。
檢查單一資源 — 要求取得單一資源的完整物件；Secret 值會替換，但會保留鍵名稱。
檢視命名空間事件和拓撲 — 取得命名空間中的近期事件（可選擇指定單一資源），或取得該命名空間中現有物件、彼此關係及健康狀態的概覽。
檢查 Argo CD 應用程式 — 列出 Argo CD 應用程式，或取得單一應用程式的同步和健康狀態。

Claude Kubernetes MCP Server

使用 Claude 回答 Kubernetes 叢集相關問題的 Go 伺服器，會運用 Kubernetes API 的脈絡，以及選用的 ArgoCD 和 GitLab 資訊。

文件：docs.blankcut.com/kubernetes-mcp-server — 快速入門、安裝、所有設定鍵與端點，以及疑難排解。

功能

讀取叢集 — 命名空間、任何資源類型（包括自訂資源）、事件，以及每個命名空間的資源、關聯與健康狀態對照表。
不使用 Claude 也能找出問題 — Warning 事件和失敗的 CronJob（包含失敗執行記錄的末尾）會在幾秒內整理成問題清單（?narrative=false）。
向 Claude 詢問資源、整個命名空間或 GitLab 合併請求的相關問題，並提供收集到的脈絡。
監控自身的 ArgoCD 存取權 — 每 60 秒檢查一次權杖是否仍可讀取 Applications，讓遺失的 RBAC 授權以錯誤呈現，而不是顯示空清單。
使用 API 金鑰或 Workload Identity Federation 向 Claude 驗證，因此無須長期有效的金鑰也能執行。
以 OpenTelemetry spans 回報模型用量，只要提供 OTLP 端點即可：每次 Claude 呼叫會產生一個 span，包含模型與權杖數量。請參閱回報模型用量。

此伺服器僅會讀取資料：它不會變更 Kubernetes、ArgoCD 或 GitLab 中的任何內容。

它是 REST API，自 1.5.0 起也支援 Model Context Protocol 伺服器：MCP 用戶端可連線至 /mcp，並將叢集讀取功能作為工具呼叫。請參閱連線 MCP 用戶端。

連線 MCP 用戶端

伺服器透過 Streamable HTTP 在 /mcp 提供 MCP，並使用與 REST API 相同的 API 金鑰（X-API-Key 或 Authorization: Bearer）。在 Claude Code 中：

claude mcp add --transport http kubernetes https://your-server.example.com/mcp \
  --header "X-API-Key: $KUBERNETES_MCP_API_KEY"

任何支援自訂標頭的 Streamable HTTP 用戶端都能以相同方式連線。目前尚未支援 stdio 傳輸，因此只能啟動本機程序的用戶端（沒有遠端連接器的 Claude Desktop）無法直接使用。

工具	回傳內容
`troubleshoot_resource`	單一資源的狀態、事件、相關物件、部署歷程，以及伺服器自行檢查發現的問題。發生故障時，請從這裡開始。
`list_namespaces`	叢集的命名空間。
`list_resources`	單一種類的資源，每個資源附有一行狀態。
`get_resource`	單一資源的完整物件。
`get_events`	命名空間中的近期事件，可選擇指定單一資源。
`namespace_topology`	命名空間中有哪些資源、彼此的關聯，以及每個資源的健康狀態。
`list_argocd_applications`、`get_argocd_application`	Argo CD 應用程式及其同步與健康狀態。

所有工具都只會讀取資料。與 REST API 有兩點不同：

工具呼叫不會呼叫 Claude。 REST 分析端點會將收集到的資料傳送給模型並回傳答案。MCP 用戶端本身就是模型，因此會取得收集到的事實並自行推理；工具呼叫不會產生模型用量費用。
絕不回傳 Secret 值。 get_resource 會保留 Secret 中的鍵名稱，並替換每個值。Chart 的預設角色完全無法讀取 Secrets；這項措施則適用於以更廣泛權限執行的伺服器。

快速入門

從 Releases 下載發行版二進位檔（Linux 和 macOS，amd64 和 arm64），建立 config.yaml：

server:
  address: ":8080"
  writeTimeout: 300
  auth:
    apiKey: "${API_KEY}"
kubernetes:
  inCluster: false          # uses $KUBECONFIG or ~/.kube/config
claude:
  apiKey: "${CLAUDE_API_KEY}"
  baseURL: "https://api.anthropic.com"
  modelID: "claude-sonnet-5"
  maxTokens: 8192

然後執行：

export API_KEY=$(openssl rand -hex 32) CLAUDE_API_KEY=sk-ant-...
./mcp-server-darwin-arm64 --config config.yaml

curl -s -H "X-API-Key: $API_KEY" \
  "http://localhost:8080/api/v1/namespaces/default/analysis?narrative=false"

快速入門會逐步說明整個流程，包括如何驗證 checksum。

安裝

方法
Helm	從發行標籤的 checkout 使用 `helm install kubernetes-mcp-server ./helm/kubernetes-mcp-server --set secrets.apiKey=... --set secrets.claudeApiKey=...`。請參閱安裝。
Docker	`blankcut/kubernetes-mcp-server`（`linux/amd64`、`linux/arm64`）；將設定檔掛載至 `/app/config.yaml`。
Binary	Releases，包含 `checksums.txt`。
Source	Go 1.26+：`cd kubernetes-claude-mcp && go build -o mcp-server ./cmd/server`。

回報模型用量

伺服器對 Claude 的每次呼叫都可以回報為一個 OpenTelemetry span，採用GenAI 語意慣例，傳送至任何 OTLP/HTTP 接收端：OpenTelemetry Collector，或可直接接收 OTLP 的後端。設定端點後才會啟用，使用標準環境變數：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318        # /v1/traces is appended
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $OTLP_TOKEN" # if the receiver wants one

Span 會記錄詢問的模型與回覆的模型、呼叫使用的權杖數量（gen_ai.usage.input_tokens，包含快取權杖、gen_ai.usage.output_tokens，以及快取讀取與寫入數量）、耗時、是否失敗（error.type），以及所屬的分析類型（kubernetes_mcp_server.analysis：resource、namespace、troubleshoot 或 merge_request）。絕不會包含提示、回應或從叢集讀取的任何資料。

變數
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	要傳送至的完整 URL，會依原樣使用。優先於下一個變數。
`OTEL_EXPORTER_OTLP_ENDPOINT`	基礎 URL；會附加 `/v1/traces`。
`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_EXPORTER_OTLP_TRACES_HEADERS`	以逗號分隔的 `name=value` 配對，每次匯出都會一併傳送。絕不記錄值。
`OTEL_EXPORTER_OTLP_TIMEOUT`、`OTEL_EXPORTER_OTLP_TRACES_TIMEOUT`	單次匯出的毫秒數。預設值為 `5000`。
`OTEL_SERVICE_NAME`、`OTEL_RESOURCE_ATTRIBUTES`	伺服器的自我描述方式。`service.name` 預設為 `kubernetes-mcp-server`；在 Pod 中，除非自行設定，否則會填入 `k8s.namespace.name` 和 `k8s.pod.name`。
`OTEL_SDK_DISABLED`	`true` 無論其他設定為何，都會關閉回報功能。

回報功能不會拖慢或導致請求失敗：spans 會排入佇列並在背景傳送；若接收端無法使用，spans 會被丟棄，且日誌中每分鐘最多只會出現一則警告。Spans 會以 OTLP/HTTP JSON 傳送；不支援 OTLP over gRPC（OTEL_EXPORTER_OTLP_PROTOCOL=grpc，連接埠 4317），因此請指定接收端的 HTTP 連接埠。MCP 工具呼叫不會呼叫模型，也不會回報任何資料。

使用 Helm chart 時，透過 extraEnv 設定變數；values.yaml 示範如何從 Secret 取得權杖。

開發

cd kubernetes-claude-mcp
go test ./...
go run ./cmd/server --config config.yaml --log-level debug

Postman 集合位於 postman/。變更記錄列於 CHANGELOG.md；歡迎貢獻 — 請參閱CONTRIBUTING.md。

捐款

請捐助我們的咖啡基金，協助我們持續創造出色的成果：請我喝咖啡

授權條款

MIT