Kubernetes MCP Server

실패한 리소스 문제 해결 — 어시스턴트에게 리소스 하나의 상태, 이벤트, 관련 객체, 배포 기록을 살펴보고 실패 원인을 찾도록 요청합니다.
네임스페이스 및 리소스 목록 확인 — 어시스턴트에게 클러스터의 네임스페이스를 나열하거나, 지정된 종류의 리소스를 각각 한 줄 상태와 함께 나열하도록 요청합니다.
단일 리소스 검사 — 리소스 하나의 전체 객체를 요청합니다. Secret 값은 대체되지만 키 이름은 유지됩니다.
네임스페이스 이벤트 및 토폴로지 검토 — 네임스페이스의 최근 이벤트(선택적으로 리소스 하나에 한정) 또는 해당 네임스페이스에 무엇이 있는지, 서로 어떻게 연결되는지, 상태가 어떤지 보여 주는 맵을 확인합니다.
Argo CD 애플리케이션 확인 — Argo CD 애플리케이션을 나열하거나 애플리케이션 하나의 동기화 및 상태 정보를 가져옵니다.

Claude Kubernetes MCP Server

Kubernetes API의 컨텍스트와 선택적으로 ArgoCD 및 GitLab을 사용해 Claude로 Kubernetes 클러스터에 관한 질문에 답하는 Go 서버입니다.

문서: docs.blankcut.com/kubernetes-mcp-server — 빠른 시작, 설치, 모든 구성 키와 엔드포인트, 문제 해결을 확인할 수 있습니다.

기능

클러스터 읽기 — 네임스페이스, 모든 리소스 유형(사용자 지정 리소스 포함), 이벤트, 리소스와 관계 및 상태를 네임스페이스별로 정리한 맵을 읽습니다.
Claude 없이 문제 찾기 — Warning 이벤트와 실패한 CronJob(실패한 실행 로그의 마지막 부분 포함)을 몇 초 만에 문제 목록으로 만듭니다 (?narrative=false).
Claude에 질문하기 — 수집한 컨텍스트를 바탕으로 리소스, 전체 네임스페이스 또는 GitLab merge request에 관해 질문합니다.
자체 ArgoCD 액세스 감시 — 60초마다 토큰으로 계속 Applications를 읽을 수 있는지 확인하므로, RBAC 권한이 사라지면 빈 목록 대신 오류가 표시됩니다.
API 키 또는 Workload Identity Federation으로 Claude 인증 — 장기간 유효한 키 없이 실행할 수 있습니다.
모델 사용량을 OpenTelemetry span으로 보고 — OTLP 엔드포인트를 지정하면 Claude 호출마다 모델과 토큰 수가 포함된 span을 하나씩 보냅니다. 모델 사용량 보고를 참조하세요.

읽기 전용입니다. Kubernetes, ArgoCD 또는 GitLab의 상태를 변경하지 않습니다.

REST API이며, 1.5.0부터는 Model Context Protocol 서버이기도 합니다. MCP 클라이언트는 /mcp에 연결해 클러스터 읽기 기능을 도구로 호출할 수 있습니다. MCP 클라이언트 연결을 참조하세요.

MCP 클라이언트 연결

서버는 /mcp에서 Streamable HTTP를 사용하며, 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 값은 반환하지 않습니다. Secret의 get_resource은 키 이름을 유지하고 각 값을 대체합니다. 차트의 기본 역할은 Secret을 전혀 읽을 수 없습니다. 이 처리는 더 넓은 권한으로 서버를 실행하는 경우에도 적용됩니다.

빠른 시작

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"

체크섬 확인을 포함한 자세한 절차는 빠른 시작을 참조하세요.

설치

방법
Helm	릴리스 태그를 체크아웃한 저장소에서 `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 하나로 보고할 수 있습니다. span은 GenAI 시맨틱 규약을 따르며, OpenTelemetry Collector 또는 OTLP를 직접 수신하는 백엔드 등 모든 OTLP/HTTP 수신기로 전송됩니다. 엔드포인트를 설정하기 전까지는 비활성화되어 있으며, 표준 변수를 사용합니다.

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`입니다. 파드에서는 직접 설정하지 않는 한 `k8s.namespace.name` 및 `k8s.pod.name`이 채워집니다.
`OTEL_SDK_DISABLED`	`true`를 설정하면 다른 설정과 관계없이 보고가 비활성화됩니다.

보고 기능은 요청을 지연시키거나 실패하게 만들 수 없습니다. span은 대기열에 넣어 백그라운드에서 전송하며, 수신기가 중단된 경우 삭제되고 로그에는 분당 최대 한 번 경고가 기록됩니다. span은 OTLP/HTTP JSON으로 전송됩니다. OTLP over gRPC(OTEL_EXPORTER_OTLP_PROTOCOL=grpc, 포트 4317)는 지원되지 않으므로 수신기의 HTTP 포트를 지정하세요. MCP 도구 호출은 모델을 호출하지 않으며 아무것도 보고하지 않습니다.

Helm 차트에서는 extraEnv을 통해 변수를 설정합니다. Secret에서 토큰을 가져오는 방법은 values.yaml를 참조하세요.

개발

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

Postman 컬렉션은 postman/에 있습니다. 변경 사항은 CHANGELOG.md에 나열되어 있습니다. 기여를 환영합니다. CONTRIBUTING.md를 참조하세요.

후원

멋진 일을 계속할 수 있도록 커피 기금에 후원해 주세요: Buy Me Coffee

라이선스

MIT