Kubectl MCP 도구
클로드, 커서 등의 AI 어시스턴트가 자연어를 통해 Kubernetes 클러스터와 상호 작용할 수 있도록 하는 Kubernetes용 MCP(Model Context Protocol) 서버입니다.
특징
핵심 쿠버네티스 운영
- [x] Kubernetes 클러스터에 연결
- [x] 포드, 서비스, 배포 및 노드를 나열하고 관리합니다.
- [x] 포드 및 기타 리소스 생성, 삭제 및 설명
- [x] Pod 로그 및 Kubernetes 이벤트 가져오기
- [x] Helm v3 작업(설치, 업그레이드, 제거) 지원
- [x] kubectl explain 및 api-resources 지원
- [x] 다음 명령에 대한 네임스페이스 선택(메모리 지속성)
- [x] 포드로 포트 포워딩
- [x] 확장 배포 및 상태 집합
- [x] 컨테이너에서 명령 실행
- [x] ConfigMaps 및 Secrets 관리
- [x] 이전 버전으로 배포 롤백
- [x] Ingress 및 NetworkPolicy 관리
- [x] 클러스터 간 컨텍스트 전환
자연어 처리
- [x] kubectl 작업에 대한 자연어 쿼리 처리
- [x] 이전 작업의 메모리가 있는 컨텍스트 인식 명령
- [x] Kubernetes 개념에 대한 인간 친화적 설명
- [x] 의도에 따른 지능형 명령 구성
- [x] 전문 도구를 사용할 수 없는 경우 kubectl로 대체
- [x] 오프라인/테스트 시나리오에 대한 모의 데이터 지원
- [x] 네임스페이스 인식 쿼리 처리
모니터링
- [x] 클러스터 상태 모니터링
- [x] 리소스 활용 추적
- [x] Pod 상태 및 상태 확인
- [x] 이벤트 모니터링 및 경고
- [x] 노드 용량 및 할당 분석
- [x] 과거 성과 추적
- [x] kubectl top을 통한 리소스 사용 통계
- [x] 컨테이너 준비 및 활성 상태 추적
보안
- [x] RBAC 검증 및 확인
- [x] 보안 컨텍스트 감사
- [x] Kubernetes API에 대한 보안 연결
- [x] 자격 증명 관리
- [x] 네트워크 정책 평가
- [x] 컨테이너 보안 스캐닝
- [x] 보안 모범 사례 시행
- [x] 역할 및 클러스터 역할 관리
- [x] ServiceAccount 생성 및 바인딩
- [x] PodSecurityPolicy 분석
- [x] RBAC 권한 감사
- [x] 보안 컨텍스트 검증
진단
- [x] 클러스터 진단 및 문제 해결
- [x] 구성 검증
- [x] 오류 분석 및 복구 제안
- [x] 연결 상태 모니터링
- [x] 로그 분석 및 패턴 감지
- [x] 리소스 제약 식별
- [x] Pod 상태 점검 진단
- [x] 일반적인 오류 패턴 식별
- [x] 잘못된 구성에 대한 리소스 검증
- [x] 자세한 활성도 및 준비성 프로브 검증
고급 기능
- [x] 다중 전송 프로토콜 지원(stdio, SSE)
- [x] 다양한 AI 어시스턴트와의 통합
- [x] 확장 가능한 도구 프레임워크
- [x] 사용자 정의 리소스 정의 지원
- [x] 네임스페이스 간 작업
- [x] 여러 리소스에 대한 일괄 작업
- [x] 지능형 리소스 관계 매핑
- [x] 복구 제안과 함께 오류 설명
- [x] 볼륨 관리 및 식별
건축학
모델 컨텍스트 프로토콜(MCP) 통합
Kubectl MCP 도구는 모델 컨텍스트 프로토콜(MCP)을 구현하여 AI 어시스턴트가 표준화된 인터페이스를 통해 쿠버네티스 클러스터와 상호 작용할 수 있도록 합니다. 아키텍처는 다음으로 구성됩니다.
- MCP 서버 : MCP 클라이언트(AI 어시스턴트)의 요청을 처리하는 호환 서버
- 도구 레지스트리 : 스키마를 사용하여 Kubernetes 작업을 MCP 도구로 등록합니다.
- 전송 계층 : stdio, SSE 및 HTTP 전송 방법을 지원합니다.
- 핵심 작업 : 도구 호출을 Kubernetes API 작업으로 변환합니다.
- 응답 포매터 : Kubernetes 응답을 MCP 호환 응답으로 변환합니다.
요청 흐름
듀얼 모드 작동
이 도구는 두 가지 모드로 작동합니다.
- CLI 모드 : Kubernetes 작업을 실행하기 위한 직접 명령줄 인터페이스
- 서버 모드 : AI 어시스턴트의 요청을 처리하기 위해 MCP 서버로 실행
설치
자세한 설치 지침은 설치 가이드를 참조하세요.
PyPI에서 직접 kubectl-mcp-tool을 설치할 수 있습니다.
지엑스피1
특정 버전의 경우:
pip install kubectl-mcp-tool==1.1.1
이 패키지는 PyPI에서 사용할 수 있습니다: https://pypi.org/project/kubectl-mcp-tool/1.1.1/
필수 조건
- 파이썬 3.9 이상
- kubectl CLI 설치 및 구성
- Kubernetes 클러스터에 대한 액세스
- pip(Python 패키지 관리자)
글로벌 설치
# Install latest version from PyPI
pip install kubectl-mcp-tool
# Or install development version from GitHub
pip install git+https://github.com/rohitg00/kubectl-mcp-server.git
지역 개발 설치
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server
# Install in development mode
pip install -e .
설치 확인
설치 후 도구가 올바르게 작동하는지 확인하세요.
# Check CLI mode
kubectl-mcp --help
참고: 이 도구는 kubectl을 직접 대체하는 것이 아니라 AI 어시스턴트가 연결하는 MCP 서버로 작동하도록 설계되었습니다. 사용 가능한 주요 명령어는 MCP 서버를 시작하는 kubectl-mcp serve 입니다.
AI 어시스턴트 사용
MCP 서버 사용
MCP 서버( kubectl_mcp_tool.mcp_server )는 FastMCP SDK를 기반으로 구축된 강력한 구현으로, 다양한 AI 어시스턴트 간에 향상된 호환성을 제공합니다.
참고 : MCP 서버 구현에 오류가 발생하는 경우, 구성에서 kubectl_mcp_tool.mcp_server kubectl_mcp_tool.minimal_wrapper 로 대체하여 최소 래퍼를 사용할 수 있습니다. 최소 래퍼는 기본적인 기능을 제공하며 구현은 더 간단합니다.
- 직접 구성
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config",
"PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
"MCP_LOG_FILE": "/path/to/logs/debug.log",
"MCP_DEBUG": "1"
}
}
}
}
- 주요 환경 변수
MCP_LOG_FILE : 로그 파일 경로(stdout 오염을 방지하기 위해 권장)MCP_DEBUG : 자세한 로깅을 위해 "1"로 설정MCP_TEST_MOCK_MODE : 실제 클러스터 대신 모의 데이터를 사용하려면 "1"로 설정합니다.KUBECONFIG : Kubernetes 구성 파일 경로KUBECTL_MCP_LOG_LEVEL : "DEBUG", "INFO", "WARNING" 또는 "ERROR"로 설정
- MCP 서버 테스트 다음을 사용하여 서버가 올바르게 작동하는지 테스트할 수 있습니다.
python -m kubectl_mcp_tool.simple_ping
python -m kubectl_mcp_tool
클로드 데스크탑
~/.config/claude/mcp.json (Windows: %APPDATA%\Claude\mcp.json )의 Claude Desktop 구성에 다음을 추가합니다.
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config"
}
}
}
}
커서 AI
MCP에서 커서 AI 설정에 다음을 추가하려면 새로운 글로벌 MCP 서버를 추가하세요.
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config",
"PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin"
}
}
}
}
글로벌 설정을 위해 이 구성을 ~/.cursor/mcp.json 에 저장합니다.
참고 : /path/to/your/.kube/config kubeconfig 파일의 실제 경로로 바꾸세요. 대부분의 시스템에서는 ~/.kube/config 입니다.
윈드서핑
~/.config/windsurf/mcp.json (Windows: %APPDATA%\WindSurf\mcp.json )의 Windsurf 구성에 다음을 추가합니다.
{
"mcpServers": {
"kubernetes": {
"command": "python",
"args": ["-m", "kubectl_mcp_tool.mcp_server"],
"env": {
"KUBECONFIG": "/path/to/your/.kube/config"
}
}
}
}
자동 구성
지원되는 모든 AI 어시스턴트를 자동으로 구성하려면 제공된 설치 스크립트를 실행하세요.
이 스크립트는 다음을 수행합니다.
- 필요한 종속성을 설치하세요
- Claude, Cursor 및 WindSurf에 대한 구성 파일을 만듭니다.
- 올바른 경로와 환경 변수를 설정하세요
- Kubernetes 연결을 테스트하세요
필수 조건
- kubectl이 설치되었고 PATH에 있습니다.
- 유효한 kubeconfig 파일
- Kubernetes 클러스터에 대한 액세스
- Helm v3(선택 사항, Helm 작업용)
예시
포드 목록
List all pods in the default namespace
애플리케이션 배포
Create a deployment named nginx-test with 3 replicas using the nginx:latest image
Pod 로그 확인
Get logs from the nginx-test pod
포트 포워딩
Forward local port 8080 to port 80 on the nginx-test pod
개발
# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server
# Install dependencies
pip install -r requirements.txt
# Install in development mode
pip install -e .
# Run the MCP server
python -m kubectl_mcp_tool
# Run tests
python -m python_tests.run_mcp_tests
프로젝트 구조
├── kubectl_mcp_tool/ # Main package
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Package entry point
│ ├── cli.py # CLI entry point
│ ├── mcp_server.py # MCP server implementation
│ ├── mcp_kubectl_tool.py # Main kubectl MCP tool implementation
│ ├── natural_language.py # Natural language processing
│ ├── diagnostics.py # Diagnostics functionality
│ ├── core/ # Core functionality
│ ├── security/ # Security operations
│ ├── monitoring/ # Monitoring functionality
│ ├── utils/ # Utility functions
│ └── cli/ # CLI functionality components
├── python_tests/ # Test suite
│ ├── run_mcp_tests.py # Test runner script
│ ├── mcp_client_simulator.py # MCP client simulator for mock testing
│ ├── test_utils.py # Test utilities
│ ├── test_mcp_core.py # Core MCP tests
│ ├── test_mcp_security.py # Security tests
│ ├── test_mcp_monitoring.py # Monitoring tests
│ ├── test_mcp_nlp.py # Natural language tests
│ ├── test_mcp_diagnostics.py # Diagnostics tests
│ └── mcp_test_strategy.md # Test strategy documentation
├── docs/ # Documentation
│ ├── README.md # Documentation overview
│ ├── INSTALLATION.md # Installation guide
│ ├── integration_guide.md # Integration guide
│ ├── cursor/ # Cursor integration docs
│ ├── windsurf/ # Windsurf integration docs
│ └── claude/ # Claude integration docs
├── compatible_servers/ # Compatible MCP server implementations
│ ├── cursor/ # Cursor-compatible servers
│ ├── windsurf/ # Windsurf-compatible servers
│ ├── minimal/ # Minimal server implementations
│ └── generic/ # Generic MCP servers
├── requirements.txt # Python dependencies
├── setup.py # Package setup script
├── pyproject.toml # Project configuration
├── MANIFEST.in # Package manifest
├── mcp_config.json # Sample MCP configuration
├── run_server.py # Server runner script
├── LICENSE # MIT License
├── CHANGELOG.md # Version history
├── .gitignore # Git ignore file
├── install.sh # Installation script
├── publish.sh # PyPI publishing script
└── start_mcp_server.sh # Server startup script
MCP 서버 도구
MCP 서버 구현( kubectl_mcp_tool.mcp_server )은 AI 어시스턴트가 Kubernetes 클러스터와 상호 작용하는 데 사용할 수 있는 포괄적인 26개 도구 세트를 제공합니다.
핵심 쿠버네티스 리소스 관리
- get_pods - 지정된 네임스페이스의 모든 포드를 가져옵니다.
- get_namespaces - 모든 Kubernetes 네임스페이스 가져오기
- get_services - 지정된 네임스페이스의 모든 서비스를 가져옵니다.
- get_nodes - 클러스터의 모든 노드를 가져옵니다.
- get_configmaps - 지정된 네임스페이스의 모든 ConfigMap을 가져옵니다.
- get_secrets - 지정된 네임스페이스의 모든 비밀을 가져옵니다.
- get_deployments - 지정된 네임스페이스의 모든 배포를 가져옵니다.
- create_deployment - 새 배포 만들기
- delete_resource - Kubernetes 리소스 삭제
- get_api_resources - Kubernetes API 리소스 나열
- kubectl_explain - kubectl explain을 사용하여 Kubernetes 리소스 설명
헬름 운영
- install_helm_chart - Helm 차트 설치
- upgrade_helm_chart - Helm 릴리스 업그레이드
- uninstall_helm_chart - Helm 릴리스 제거
보안 운영
- get_rbac_roles - 지정된 네임스페이스의 모든 RBAC 역할을 가져옵니다.
- get_cluster_roles - 클러스터 전체의 모든 RBAC 역할 가져오기
모니터링 및 진단
- get_events - 지정된 네임스페이스의 모든 이벤트를 가져옵니다.
- get_resource_usage - kubectl top을 통해 리소스 사용 통계를 가져옵니다.
- health_check - API 서버에 ping을 보내 클러스터 상태를 확인합니다.
- get_pod_events - 특정 Pod에 대한 이벤트 가져오기
- check_pod_health - 포드의 상태 확인
- get_logs - Pod에서 로그 가져오기
클러스터 관리
- switch_context - 현재 kubeconfig 컨텍스트를 전환합니다.
- get_current_context - 현재 kubeconfig 컨텍스트 가져오기
- port_forward - 로컬 포트를 Pod 포트로 전달
- scale_deployment - 배포 확장
모든 도구는 성공/오류 정보와 관련 세부 정보가 포함된 구조화된 데이터를 반환하므로 AI 도우미가 응답을 쉽게 처리하고 이해할 수 있습니다.
기여하다
기여를 환영합니다! 풀 리퀘스트를 제출해 주세요.
- 저장소를 포크하세요
- 기능 브랜치를 생성합니다(
git checkout -b feature/amazing-feature ) - 변경 사항을 커밋하세요(
git commit -m 'Add some amazing feature' ) - 브랜치에 푸시(
git push origin feature/amazing-feature ) - 풀 리퀘스트 열기
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.