K8s MCP 서버
CI Status
Release Status
codecov
Image Tags
Image Size
Python Version
License: MIT
K8s MCP 서버는 Anthropic의 모델 컨텍스트 프로토콜(Model Context Protocol, MCP)을 구현하는 Docker 기반 서버로, Claude가 쿠버네티스 CLI 도구(kubectl, istioctl, helm, argocd)를 안전하고 컨테이너화된 환경에서 실행할 수 있도록 합니다.
데모: WordPress 배포 및 문제 해결
세션 1: k8s-mcp-server와 Helm CLI를 사용하여 claude-demo 네임스페이스에 WordPress 애플리케이션을 배포한 다음, MariaDB StatefulSet의 크기를 0으로 조정하여 의도적으로 장애를 발생시키는 과정.
세션 2: k8s-mcp-server를 사용하여 kubectl 명령을 통해 손상된 WordPress 사이트를 진단하고, 누락된 데이터베이스 문제를 식별한 후, StatefulSet의 크기를 늘리고 Ingress 접근을 구성하여 이를 해결하는 문제 해결 세션.
Demo
작동 원리 (How It Works)
flowchart LR
A[사용자(User)] --> |K8s 질문 요청| B[Claude]
B --> |MCP를 통해 명령 전송| C[K8s MCP 서버]
...
Claude는 다음을 통해 사용자에게 도움을 줄 수 있습니다:
- 복잡한 Kubernetes 개념 설명
- 클러스터에 대한 명령어 실행
- 문제 해결(Troubleshooting) 지원
- 최적화 제안
- Kubernetes 매니페스트 작성
Claude 데스크톱을 이용한 빠른 시작 (Quick Start with Claude Desktop)
2분 이내에 Claude를 사용하여 Kubernetes 클러스터 작업을 도와받으세요:
-
Claude 데스크톱 구성 파일 생성 또는 업데이트:
- macOS:
$HOME/Library/Application Support/Claude/claude_desktop_config.json 수정
- Windows:
%APPDATA%\Claude\claude_desktop_config.json 수정
- Linux:
$HOME/.config/Claude/claude_desktop_config.json 수정
{
"mcpServers": {
"kubernetes": {
...
2. **Claude 데스크톱 재시작**
- 재시작 후, 입력 필드의 오른쪽 하단에 도구 아이콘(🔨)이 표시됩니다.
- 이는 Claude가 이제 MCP 서버를 통해 K8s 도구에 접근할 수 있음을 나타냅니다.
3. **Claude Desktop에서 K8s 도구 직접 사용하기**:
- "사용 가능한 쿠버네티스 컨텍스트는 무엇인가요?"
- "기본 네임스페이스의 모든 파드를 보여주세요"
- "nginx:1.21의 복제본 3개로 배포(deployment)를 생성하세요"
- "'prod' 네임스페이스에 있는 StatefulSet 'database'에 무엇이 잘못되었는지 설명해 주세요"
- "Helm을 사용하여 bitnami/wordpress 차트를 배포하고 서비스 유형을 LoadBalancer로 설정하세요"
> **참고**: Claude Desktop은 K8s 명령을 자동으로 MCP 서버를 통해 라우팅하여, Claude 인터페이스를 벗어나지 않고도 클러스터에 대한 자연스러운 대화를 가능하게 합니다.
> **클라우드 제공업체**: AWS EKS, GKE 또는 Azure AKS의 경우 추가 구성이 필요합니다. [클라우드 제공업체 지원](./docs/cloud-providers.md) 가이드를 참조하십시오.
## 기능 (Features)
- **다중 쿠버네티스 도구**: 하나의 컨테이너에 `kubectl`, `helm`, `istioctl`, 및 `argocd` 포함
- **클라우드 제공업체 지원**: AWS EKS, Google GKE, Azure AKS를 네이티브로 지원
- **보안**: 엄격한 명령 검증을 거쳐 비(非)루트 사용자 권한으로 실행
- **명령 파이프라인**: `jq`, `grep`, `sed`와 같은 일반적인 Unix 도구 지원
- **쉬운 구성**: 맞춤 설정을 위한 간단한 환경 변수 제공
## 전송 프로토콜 (Transport Protocols)
서버는 `K8S_MCP_TRANSPORT`를 통해 구성되는 세 가지 전송 프로토콜을 지원합니다:
| 전송 방식 | 설명 | 기본값 |
| :--- | :--- | :--- |
| `stdio` | 표준 입출력 (Claude Desktop 기본값) | 예시 |
| ... |
예시: Streamable HTTP 전송 방식을 사용하는 경우:
```bash
docker run --rm -p 8000:8000 \
-v ~/.kube:/home/appuser/.kube:ro \
-e K8S_MCP_TRANSPORT=streamable-http \
...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
참고: HTTP 전송 방식을 사용하여 Docker에서 실행할 때, 서버는 올바른 포트 매핑을 위해 자동으로 0.0.0.0에 바인딩됩니다. Docker 외부에서는 127.0.0.1에 바인딩됩니다.
문서화 (Documentation)
사용 예시 (Usage Examples)
연결한 후에는 자연어(natural language)를 사용하여 Claude에게 Kubernetes 작업을 요청할 수 있습니다:
flowchart TB
subgraph "기본 명령어"
A1["기본 네임스페이스의 모든 파드를 보여줘"]
...
Claude는 사용자의 의도를 이해하고, 요청에 따라 적절한 kubectl, helm, istioctl 또는 argocd 명령을 실행할 수 있습니다. 이후 출력 결과를 간단한 용어로 설명하거나 문제 해결을 도울 수 있습니다.
고급 Claude Desktop 구성 (Advanced Claude Desktop Configuration)
Claude Desktop을 구성하여 Kubernetes 워크플로우를 최적화하세요:
특정 클러스터 및 네임스페이스 지정 (Target Specific Clusters and Namespaces)
{
"mcpServers": {
"kubernetes": {
...
AWS EKS 클러스터 연결 (Connect to AWS EKS Clusters)
{
"mcpServers": {
"kubernetes": {
...
Google GKE 클러스터 연결 (Connect to Google GKE Clusters)
{
"mcpServers": {
"kubernetes": {
...
Azure AKS 클러스터 연결 (Connect to Azure AKS Clusters)
{
"mcpServers": {
"kubernetes": {
...
허용적 보안 모드 (Permissive Security Mode)
{
"mcpServers": {
"kubernetes": {
...
상세한 보안 구성 옵션은 Security Documentation을 참조하세요.
라이선스 (License)
본 프로젝트는 MIT License 하에 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참고하십시오.
