mcp-kubernetes

Kubernetes용 Model Context Protocol 서버입니다. MCP를 지원하는 클라이언트(Claude Desktop, Claude Code 등)에서 여러 컨텍스트에 걸쳐 Kubernetes 클러스터를 검사하고 운영할 수 있게 해주며, 동작은 전적으로 플래그로 제어됩니다.

설계 목표는 기본적으로 안전함입니다. 서버는 읽기 전용으로 시작하고, 네임스페이스와 컨텍스트의 허용 목록(allowlist)으로 범위를 제한하며, 시스템 네임스페이스를 변경으로부터 보호하고, 위험한 작업(delete, apply, exec)은 명시적 옵트인 뒤에 숨깁니다.

기능

• 멀티 클러스터 — 모든 도구는 선택적으로 context를 받습니다. 허용 목록을 사용해 사용 가능한 컨텍스트를 범위로 제한할 수 있습니다.

• 접근 모드 — read-only → read-write → admin로 계층화되어 있어, 어떤 모드도 자신의 수준보다 높은 도구를 노출하지 않습니다.

• 보안 플래그 — 네임스페이스 허용 목록, 보호된 네임스페이스, 컨텍스트 허용 목록과 함께 delete / apply / exec에 대한 독립적인 옵트인, dry-run, JSON 감사 로깅(아래 참조)을 제공합니다.

• 표준 인증 — kube-config(또는 클러스터 내 서비스 계정)를 사용합니다. 서버는 자격 증명을 저장하지 않습니다.

Related MCP server: k8s-mcp-go

보안 모델

계층은 독립적입니다. 예를 들어 admin 모드에서도 세 가지 옵트인이 전부 false이면 배포를 재시작하고 확장할 수는 있지만, 리소스를 삭제하거나 파이드에 명령을 실행할 수는 없습니다.

도구

읽기 (read-only+): list_contexts, list_namespaces, list_pods, get_pod, get_pod_logs, list_deployments, list_services, list_nodes, list_events, get_resource

쓰기 (read-write+): scale_deployment, restart_deployment, set_deployment_image, create_namespace, apply_manifest (이것은 K8S_ALLOW_APPLY 필요)

관리 (admin): delete_resource (이것은 K8S_ALLOW_DELETE 필요), exec_in_pod (이것은 K8S_ALLOW_EXEC 필요)

MCP 클라이언트에서 사용하기

Claude Code, Claude Desktop, Cursor, OpenAI Codex CLI, Windsurf, VS Code(Copilot) 등 모든 MCP 클라이언트에서 동작합니다. 클라이언트별 설정은 **docs/CLIENTS.md**를 참조하세요.

설치

npm install
npm run build

Claude Desktop / Claude Code에서 실행

MCP 클라이언트 구성에 다음을 추가하세요:

{
  "mcpServers": {
    "kubernetes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-kubernetes/dist/index.js"],
      "env": {
        "KUBECONFIG_PATH": "/Users/you/.kube/config",
        "K8S_MODE": "read-only",
        "K8S_CONTEXT_ALLOWLIST": "staging",
        "K8S_NAMESPACE_ALLOWLIST": "app,web"
      }
    }
  }
}

K8S_MODE를 read-write로 올리면 스케일링/재시작이 가능하며, 삭제나 exec를 허용하려는 경우에만 관련 K8S_ALLOW_* 플래그와 함께 admin으로 올리세요.

개발

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

배포

이 서버는 공식 MCP 레지스트리를 위한 server.json과 npm 소유권 검증을 위한 mcpName을 함께 제공합니다. npm 배포 및 MCP 레지스트리, Smithery, Glama, Cursor, PulseMCP 등록에 대해서는 **PUBLISHING.md**를 참조하세요.

라이선스

MIT