kubectl-mcp

AI 에이전트가 평범한 영어로 Kubernetes 클러스터를 검사할 수 있게 해주는 MCP(Model Context Protocol) 서버 — *"지난 1시간 동안 재시작된 파드는 무엇인가요?"*라고 물어보면 실제 답변을 받을 수 있습니다.

Teresa Tran이 만들었습니다.

왜 필요한가

LLM 어시스턴트는 kubectl 명령어를 설명하는 데는 뛰어나지만, 실제로 안전하게 실행하는 데는 형편없습니다. kubectl-mcp는 읽기 전용 클러스터 검사를 에이전트가 호출할 수 있는 MCP 도구 세트로 노출하여, "내 클러스터 확인"을 복사-붙여넣기-기도하기에서 실제 대화로 바꿔줍니다.

• 설계상 읽기 전용. apply도, delete도, exec도 없습니다. 서버는 오직 검사만 합니다.

• 기본값은 모의(mock) 모드. 시드된 가짜 클러스터가 포함되어 있어 실제 클러스터 없이 30초 안에 사용해볼 수 있습니다.

• 준비되면 실제 모드. KUBECONFIG를 가리키면 공식 Kubernetes Python 클라이언트를 통해 실제 클러스터를 쿼리합니다.

Related MCP server: mcp-k8s-context-server

설치

pip install kubectl-mcp                # mock mode (default)
pip install "kubectl-mcp[real]"        # + real-cluster support (kubernetes client)

또는 소스에서:

git clone https://github.com/teresa-tran/kubectl-mcp.git
cd kubectl-mcp
pip install -e ".[real,dev]"

단독 실행 (동작 확인)

kubectl-mcp --help                     # show flags
kubectl-mcp --list-tools               # print every MCP tool + its schema
kubectl-mcp --demo list_pods           # run a tool once against the mock cluster
kubectl-mcp --demo find_restarted_pods --arg since_minutes=120

MCP 클라이언트에 연결

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(맥) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)에 추가:

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp"
    }
  }
}

실제 클러스터 모드의 경우:

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp",
      "env": {
        "KUBECTL_MCP_MODE": "real",
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

Claude Desktop을 재시작하세요. 이제 *"production 네임스페이스의 파드를 나열해줘"*라고 물어보면 실제 답변을 받을 수 있습니다.

기타 MCP 호환 클라이언트

stdio MCP를 지원하는 모든 클라이언트(Cursor, Cline, Continue, 커스텀 에이전트)는 동일한 방식으로 작동합니다 — kubectl-mcp 바이너리를 가리키기만 하면 됩니다.

노출되는 도구

모든 도구에는 JSON Schema가 있습니다 — LLM은 별도 작업 없이 적절한 인자 검증을 받을 수 있습니다.

구성

환경 변수:

모의 클러스터

기본 모의 클러스터는 src/kubectl_mcp/mock_data.json에 포함되어 있으며 다음을 포함합니다:

• 3개의 네임스페이스: default, production, staging

• 정상, 크래시루프, 최근 재시작 상태를 아우르는 ~15개 파드

• 디플로이먼트, 서비스, 최근 이벤트 스트림

• 일부 파드의 재시작 횟수가 0보다 커서 find_restarted_pods가 실제 결과를 반환합니다

특정 시나리오를 데모하고 싶다면 KUBECTL_MCP_MOCK_DATA=/path/to/your.json을 설정하여 재정의할 수 있습니다.

설계 노트

• 구조적으로 읽기 전용. KubernetesBackend 프로토콜은 읽기 메서드만 정의합니다. 실제 모드에서도 클러스터 상태를 변경할 수 있는 코드 경로가 없습니다.

• 백엔드 교체 가능. MockBackend와 RealBackend는 동일한 프로토콜을 구현합니다. 세 번째 백엔드(예: 캐시된 스냅샷)를 추가하는 것은 파일 하나면 충분합니다.

• 오류는 예외로 처리, 조용한 null이 아님. ResourceNotFound, NamespaceNotFound 등은 도움이 되는 메시지와 함께 McpError로 전파되어 에이전트가 방향을 수정할 수 있습니다.

• stdio 전송. 모든 MCP 도구 호출은 MCP 사양을 정확히 따르는 stdio를 통한 JSON-RPC입니다.

개발

pip install -e ".[real,dev]"
pytest                                 # run tests
ruff check src tests                   # lint
kubectl-mcp --demo list_pods --arg namespace=production   # smoke test

로드맵

• 시드 데이터가 포함된 모의 백엔드

• kubernetes Python 클라이언트를 통한 실제 백엔드

• 읽기 전용 도구 표면

• CI/스모크 테스트용 단독 --demo 모드

• 멀티 클러스터 지원(--context 플래그)

• 메트릭 도구(metrics.k8s.io를 통한 CPU/메모리)

• 고빈도 쿼리를 위한 선택적 캐싱 레이어

라이선스

MIT © 2026 Teresa Tran