Flux159/mcp-server-kubernetes

MCP Server Kubernetes – AI 기반 Kubernetes 제어

무엇인가요 – npx mcp-server-kubernetes로 실행할 수 있는 작고 Node 스타일의 서버입니다. 이 서버는 Model Context Protocol (MCP)를 지원하며, AI 기반 보조 도구(Claude, Codex, VS Code 확장 프로그램, Cursor 등)가 로컬 Kubernetes 클러스터에 대해 kubectl과 유사한 명령어, Helm 작업, 포트 포워딩, 노드 유지보수, 진단 작업을 수행할 수 있게 해줍니다.

왜 중요한가요 – Kubernetes 작업을 표준 MCP 인터페이스를 통해 노출함으로써 개발자는 CLI 코드를 작성하지 않고도 LLM에게 파드 목록 보기, 매니페스트 적용, 배포 스케일링, 또는 실패한 파드 진단을 요청할 수 있습니다. 서버는 안전을 위해 읽기 전용 모드로 실행될 수 있으며, 옵션으로 OpenTelemetry 추적을 내보낼 수 있습니다.

빠른 시작

사전 요구 사항 – kubectl, 유효한 ~/.kube/config, 그리고 (선택 사항으로) Helm v3. Bun 런타임(bun.sh)을 설치하세요.

실행 –

bun install          # 종속성 설치
npx mcp-server-kubernetes   # 서버 시작 (STDIO 또는 SSE 전송 방식)

AI 클라이언트 연결 – 예: Claude 데스크톱, VS Code MCP 확장 프로그램, 또는 mcp-chat CLI:
```
npx mcp-chat --server "npx mcp-server-kubernetes"
```
클라이언트는 자동으로 현재 kubectl 컨텍스트를 감지합니다.

핵심 기능 (MCP 도구로 노출됨)

카테고리	도구 (예시)	설명
리소스 CRUD	`kubectl_get`, `kubectl_create`, `kubectl_apply`, `kubectl_delete`	어떤 K8s 객체든 목록 보기, 생성, YAML 적용, 삭제.
검사	`kubectl_describe`, `kubectl_logs`, `explain_resource`	상세 설명, 로그 끝 부분 보기, 자연어 기반 설명 제공.
관리	`kubectl_scale`, `kubectl_patch`, `kubectl_rollout`, `node_management`	배포 스케일링, 필드 패치, 롤아웃 제어, 노드 코르돈/드레인.
Helm	`install_helm_chart`, `upgrade_helm_chart`, `helm_template_apply`, `helm_template_uninstall`	차트 설치/업그레이드, 또는 인증 문제를 피하기 위해 템플릿 렌더링 후 적용.
포트 포워딩	`port_forward`, `stop_port_forward`	파드/서비스를 로컬에서 노출.
진단	`k8s-diagnose`	문제 발생한 파드에 대한 안내식 진단 흐름.
유틸리티	`kubectl_context`, `list_api_resources`, `ping`	컨텍스트 전환, API 그룹 목록 보기, 건강 상태 확인.

모든 도구는 비破壊 모드(ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true)에서 필터링 가능하여, 읽기 전용 및 안전한 생성/업데이트 작업만 남깁니다.

관찰성 (선택 사항)

환경 변수로 활성화:

export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
npx mcp-server-kubernetes

모든 도구 호출에 대해 추적(이름, 지속 시간, 성공/실패, K8s 컨텍스트 등)을 수행하며, OTLP 호환 백엔드(Jaeger, Grafana Tempo, Datadog, AWS X‑Ray 등)로 내보낼 수 있습니다.
샘플링, 구성, 배포 예제는 docs/OBSERVABILITY.md를 참조하세요.

개발 및 기여

빌드 – bun run dev (감시 모드), bun run test, bun run build.
로컬 테스트 – Model Context Protocol inspector 또는 포함된 mcp-chat CLI 사용.
기여 – CONTRIBUTING.md를 따르세요; PR을 환영합니다.
릴리스 워크플로우 – GitHub에서 새 vX.Y.Z 태그를 지정하면 CI가 자동으로 빌드하고 npm 패키지로 게시합니다.

누가 사용할 수 있을까

에디터에서 직접 클러스터를 관리할 수 있는 AI 보조 개발자.
안전하고 감사 가능한 Kubernetes 작업이 필요한 챗옵스 봇을 구축하는 운영 팀.
Claude, Cursor 또는 사용자 정의 보조 도구에 연결할 수 있는 MCP 호환 백엔드를 찾는 도구 제작자.

인용

프로젝트를 인용할 경우 다음 BibTeX 항목을 사용하세요:

@software{Patel_MCP_Server_Kubernetes_2024,
  author = {Patel, Paras and Sonwalkar, Suyog},
  month = jul,
  title = {{MCP Server Kubernetes}},
  url = {https://github.com/Flux159/mcp-server-kubernetes},
  version = {2.5.0},
  year = {2024}
}