Kubernetes MCP Server

Name: Kubernetes MCP Server MCP Server
Author: containers

왜 쓰나요

핵심 기능

kubeconfig가 알고 있는 모든 클러스터에서 작동
멀티 컨텍스트 지원 — 호출별로 컨텍스트 전환
표준 동사: list, get, create, apply, patch, delete, logs, exec, port-forward
OpenShift Routes, Projects, BuildConfigs 지원
Helm 헬퍼: 릴리스 목록, 값 가져오기
RBAC 준수 — Claude는 토큰이 가진 것만 얻음
안전한 배포를 위한 읽기 전용 모드

라이브 데모

실제 사용 모습

kubernetes-mcp-containers.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "kubernetes-mcp-containers": {
      "command": "npx",
      "args": [
        "-y",
        "kubernetes-mcp-server@latest"
      ],
      "env": {
        "KUBECONFIG": "${HOME}/.kube/config"
      }
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "kubernetes-mcp-containers": {
      "command": "npx",
      "args": [
        "-y",
        "kubernetes-mcp-server@latest"
      ],
      "env": {
        "KUBECONFIG": "${HOME}/.kube/config"
      }
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "kubernetes-mcp-containers": {
      "command": "npx",
      "args": [
        "-y",
        "kubernetes-mcp-server@latest"
      ],
      "env": {
        "KUBECONFIG": "${HOME}/.kube/config"
      }
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "kubernetes-mcp-containers": {
      "command": "npx",
      "args": [
        "-y",
        "kubernetes-mcp-server@latest"
      ],
      "env": {
        "KUBECONFIG": "${HOME}/.kube/config"
      }
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "kubernetes-mcp-containers",
      "command": "npx",
      "args": [
        "-y",
        "kubernetes-mcp-server@latest"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "kubernetes-mcp-containers": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "kubernetes-mcp-server@latest"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add kubernetes-mcp-containers -- npx -y kubernetes-mcp-server@latest

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Kubernetes MCP Server

Kubernetes 프로덕션 인시던트 트리아지

👤 SRE / 플랫폼 엔지니어 ⏱ ~10 min intermediate

언제 쓸까: 앱이 프로덕션에서 오작동하고 창 전환 없이 파드, 이벤트, 로그를 확인해야 할 때.

사전 조건

클러스터에 대한 접근 권한이 있는 kubeconfig — 표준 aws eks update-kubeconfig 또는 동등한 명령

흐름

비정상 파드 찾기

k8s: prod-us-east 컨텍스트, checkout 네임스페이스에서 Running 상태가 아닌 파드를 나열하세요. 이유 + 재시작 횟수 포함.✓ 복사됨

→ 상태, 이유, 재시작 횟수와 함께 파드 표시됨
이벤트 가져오기

해당 네임스페이스에서 지난 30분의 이벤트를 시간순으로 정렬하여 가져오세요.✓ 복사됨

→ 이벤트 목록; OOMKilled 또는 ImagePullBackOff가 있으면 표시됨
로그 가져오기

가장 최근에 재시작된 파드에서 이전 컨테이너의 로그 마지막 200줄을 가져오세요.✓ 복사됨

→ 스택 트레이스 / 원인 표시
진단

종합: 가능한 근본 원인과 해야 할 것은 무엇인가요? 구체적으로 말해주세요.✓ 복사됨

→ 구체적인 다음 단계 (예: 메모리 제한 증가 + 롤아웃)

결과: 인용된 파드 이름 + 로그 라인과 함께 5분 이내 트리아지

함정

이전 컨테이너가 없으면 로그를 가져올 수 없음 — 파드가 한 번만 재시작된 경우, 현재 컨테이너 로그 확인, 충돌한 경우에만 이전 컨테이너 확인
잘못된 컨텍스트 — 호출별로 항상 컨텍스트를 지정; 현재 컨텍스트 드리프트에 의존하지 말 것

함께 쓰기: sentry · github

클러스터 컨텍스트를 사용하여 Deployment 작성

👤 매니페스트를 작성하는 앱 개발자 ⏱ ~20 min intermediate

언제 쓸까: 새 Deployment가 필요하고 클러스터 규약에 맞게 하고 싶을 때.

흐름

기존 것 검사

k8s: apps 네임스페이스에서 샘플 기존 Deployment를 가져오세요. 레이블, 보안 컨텍스트, 리소스를 맞추고 싶습니다.✓ 복사됨

→ 대표적인 Deployment YAML 반환됨
새 것 작성

이제 image-resizer:1.2.0에 대한 새 Deployment를 작성하세요. 복제본 2개, 포트 8080, 규약을 준수하세요.✓ 복사됨

→ 클러스터 규약을 따르는 YAML
드라이런 apply

--dry-run=server로 apply하세요. 유효성 검사 오류를 보고하세요.✓ 복사됨

→ 서버 측 유효성 검사 통과; ApplyConfiguration 드리프트 없음

결과: 처음 시도에 클러스터 관용구에 맞는 매니페스트

함정

PSA 레이블 忘忘 — 먼저 네임스페이스의 pod-security 레이블 읽기

함께 쓰기: filesystem · github

네임스페이스 전체에서 Helm 릴리스 감사

👤 플랫폼 팀 ⏱ ~25 min intermediate

언제 쓸까: 분기별: 플릿 전체에서 오래된 차트 버전 찾기.

흐름

모든 릴리스 나열

k8s/Helm: 모든 네임스페이스의 모든 릴리스를 나열하세요. 차트 + 버전 + appVersion 포함.✓ 복사됨

→ 전체 릴리스 표
오래된 것 강조

각각에 대해 최신 차트 버전과 비교하세요 (검색 가능). 최신 버전보다 2개 이상 마이너 버전 뒤처진 릴리스를 표시하세요.✓ 복사됨

→ 현재 vs 최신이 있는 표시된 집합

결과: 우선순위 순서가 있는 업그레이드 백로그

함정

Helm 2 잔재가 섞임 — v3 릴리스로 필터링; MCP는 Helm 3만 처리

조합

다른 MCP와 조합해 10배 효율

kubernetes-mcp-containers + sentry

오류와 파드 재시작 상관관계

Sentry: 14:00 오류 급증. k8s: 그 시간에 checkout ns에서 파드 재시작이 있었나요?✓ 복사됨

kubernetes-mcp-containers + github

매니페스트 수정이 포함된 PR 열기

k8s: 잘못된 메모리 제한 식별. GitHub: helm/values.yaml에서 이를 높이는 PR 열기.✓ 복사됨

kubernetes-mcp-containers + mcp-grafana

k8s 상태와 Prometheus 교차 참조

k8s: 파드가 재시작 중. Grafana: 해당 파드의 메모리 사용 기록 가져오기.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
list_resources	context?, namespace?, kind: str, label_selector?	탐색	1 API call
get_resource	context?, namespace?, kind, name	특정 항목 검사	1 call
apply_yaml	context?, yaml: str, dry_run?: bool	생성 또는 업데이트	1 call
delete_resource	context?, namespace?, kind, name	제거	1 call
get_logs	context?, namespace, pod, container?, previous?, tail?	런타임 검사	1 call
exec	context?, namespace, pod, container?, command: str[]	컨테이너 내부 진단	1 call
list_events	context?, namespace, since?	OOMKilled/ImagePullBackOff 찾기	1 call
list_helm_releases	context?, namespace?	Helm 감사	1 call

비용 및 제한

운영 비용

API 쿼터: kube-apiserver QPS에 바인딩 (기본 ~50)
호출당 토큰: 200–8000 (로그/yaml이 클 수 있음)
금액: 무료 OSS; 클러스터 요금 적용
팁: 로그에 --tail 적극 사용; 대규모 클러스터에서 get pods -o yaml -A 절대 사용 금지

보안

권한, 시크릿, 파급범위

최소 스코프: whatever your kubeconfig user has — RBAC enforced server-side

자격 증명 저장: kubeconfig 파일; 클라우드 제공자를 통해 교체

데이터 외부 송신: 사용자의 kube API 엔드포인트만

절대 부여 금지: cluster-admin to a kubeconfig used with an LLM

최소 권한 ServiceAccount kubeconfig 사용; cluster-admin은 절대 사용 금지
Claude가 apply/delete를 할 수 없어야 한다면 --read-only 플래그 설정
exec에 주의 — Claude가 파드 내부에서 무엇이든 실행할 수 있음

문제 해결

자주 발생하는 오류와 해결

Unauthorized / 403

RBAC가 해당 동사를 거부함; 해당 사용자에 대해 kubectl auth can-i 확인

확인: kubectl auth can-i get pods -n checkout

연결 거부

VPN이 없거나 컨텍스트가 잘못된 엔드포인트를 가리킴; kubectl cluster-info 확인

Apply 거부: 유효성 검사 오류

먼저 dry_run=server로 실행; 정확한 오류 표시

로그가 너무 큼

tail 파라미터 사용; 기본값은 전체 로그

대안