KubeAid MCP

KubeAid로 관리되는 Kubernetes 클러스터를 위한 MCP 서버입니다. Claude Code, Claude Desktop, Cursor 또는 MCP 호환 클라이언트에 연결하여 "어떤 앱이 동기화되지 않았지?", "kube-prometheus가 왜 degraded 상태지?", "cert-manager 앱을 동기화해줘" 같은 질문을 할 수 있습니다 — 모델은 이 서버의 도구를 호출하여 답변하며, 이 도구들은 사용자 자신의 kubeconfig 자격 증명을 통해 클러스터와 통신합니다.

공식 @modelcontextprotocol/sdk와 @kubernetes/client-node를 기반으로 TypeScript로 구축되었습니다.

저자: Deep Poharkar

왜 KubeAid 전용인가?

KubeAid는 GitOps 방식으로 클러스터를 운영합니다: 모든 애플리케이션은 kubeaid-config 저장소에서 생성된 ArgoCD Application이며, 자동 동기화는 기본적으로 비활성화되어 있습니다 — Git과 클러스터 간의 드리프트는 정상적인 현상이며 의도적인 동기화를 기다립니다. 일반적인 Kubernetes 어시스턴트는 이러한 워크플로우를 이해하지 못합니다. 이 서버는 이해합니다:

• ArgoCD Application CR은 일급 시민입니다: 동기화 상태, 상태, 실패 조건, 드리프트된 리소스가 한 번의 도구 호출로 확인됩니다.

• 동기화는 KubeAid에서의 명시적인 "지금 배포" 결정으로 모델링됩니다 — 옵트인 플래그로 제한되고, dry_run을 지원하며, 보호 대상으로 표시한 컨텍스트에서는 절대 허용되지 않습니다.

• 번들된 프롬프트는 KubeAid 운영 습관을 인코딩합니다: 동기화 전에 드리프트를 검토하고, 클러스터를 직접 수정하는 대신 kubeaid-config 저장소에서 수정합니다.

도구

읽기 도구 — 항상 등록됨:

쓰기 도구 — KUBEAID_MCP_ALLOW_WRITES=true일 때만 등록됨:

모든 도구는 선택적 context 인수를 사용하여 단일 서버 프로세스에서 kubeconfig의 모든 클러스터를 대상으로 할 수 있습니다.

프롬프트

프롬프트는 클라이언트에서 슬래시 명령/메뉴 항목으로 나타나며 위 도구를 사용하여 모델을 워크플로우로 안내합니다:

빠른 시작

Node.js 20+ 필요.

git clone <your-repo-url> kubeaid-mcp
cd kubeaid-mcp
npm install
npm run build

Claude Code

claude mcp add kubeaid -- node "$(pwd)/dist/index.js"

기본적으로 읽기 전용입니다. 프로덕션을 건드릴 수 없게 하면서 쓰기를 활성화하려면:

claude mcp add kubeaid \
  -e KUBEAID_MCP_ALLOW_WRITES=true \
  -e KUBEAID_MCP_PROTECTED_CONTEXTS=prod-cluster-1,prod-cluster-2 \
  -- node "$(pwd)/dist/index.js"

Claude Desktop

설정 → 개발자 → 로컬 MCP 서버를 활성화한 다음, 해당 페이지에서 열리는 구성 파일에 추가하세요:

{
  "mcpServers": {
    "kubeaid": {
      "command": "node",
      "args": ["/absolute/path/to/kubeaid-mcp/dist/index.js"],
      "env": {
        "KUBEAID_MCP_ALLOW_WRITES": "true",
        "KUBEAID_MCP_PROTECTED_CONTEXTS": "prod-cluster-1"
      }
    }
  }
}

이후 앱을 완전히 종료하고 다시 엽니다.

구성

모든 구성은 환경 변수이며 시작 시 한 번 읽습니다:

안전 모델

세 가지 독립적인 계층:

1. 기능 게이팅 — 쓰기가 비활성화된 경우(기본값), 변경 도구는 절대 등록되지 않으므로 모델이 볼 수조차 없습니다.

2. 보호 컨텍스트 — 모든 변경 핸들러는 대상 컨텍스트를 KUBEAID_MCP_PROTECTED_CONTEXTS와 다시 확인하고, 모델이 무엇을 요청하든 보호된 컨텍스트를 거부합니다.

3. 클라이언트 확인 — 도구는 MCP readOnlyHint/destructiveHint 주석을 포함하므로, 잘 동작하는 클라이언트는 위험한 호출 전에 사용자에게 확인을 요청합니다.

서버는 자체 자격 증명을 보유하지 않습니다. kubeconfig ID가 RBAC를 통해 이미 권한을 부여받은 작업만 수행할 수 있습니다.

개발

npm run typecheck   # strict TS, no emit
npm run build       # compile to dist/
npm run smoke       # spawn the server, MCP handshake, list tools + prompts
KUBEAID_MCP_ALLOW_WRITES=true npm run smoke   # verify write tools register

스모크 테스트는 클러스터가 필요 없습니다 — stdio를 통해 원시 JSON-RPC 프로토콜을 구동합니다.

로드맵

• check_chart_updates: 배포된 차트 버전을 업스트림 KubeAid argocd-helm-charts 디렉토리와 비교.

• Sealed-secrets 도우미: SealedSecret 상태 나열, 실패한 unseal 플래그.

• Prometheus/Alertmanager 도구: KubeAid가 제공하는 kube-prometheus 스택에서 발생하는 알림 표시.

감사의 말

• KubeAid by Obmondo — 이 서버가 구축된 클러스터 관리 스택.

• Argo CD — KubeAid의 기반이 되는 GitOps 엔진.

라이선스

MIT © 2026 Deep Poharkar