Azure/mcp-kubernetes
요약
mcp-kubernetes는 AI 어시스턴트가 Kubernetes 클러스터와 상호작용할 수 있도록 돕는 Model Context Protocol(MCP) 서버입니다. Claude, Cursor 등 AI 도구가 자연어 명령을 통해 리소스 쿼리, kubectl 실행, 상태 진단 등을 수행할 수 있게 지원합니다.
핵심 포인트
- AI 도구와 Kubernetes 간의 가교 역할 수행
- 자연어를 통한 Kubernetes 리소스 관리 및 진단 가능
- readonly, readwrite, admin 등 세분화된 액세스 권한 제어
- kubectl 및 helm 등 다양한 도구 통합 지원
mcp-kubernetes는 AI 어시스턴트가 Kubernetes 클러스터와 상호작용할 수 있도록 지원하는 Model Context Protocol (MCP) 서버입니다. 이 서버는 AI 도구(Claude, Cursor, GitHub Copilot 등)와 Kubernetes 사이의 가교 역할을 하며, 자연어 요청을 Kubernetes 작업으로 변환하고 AI 도구가 이해할 수 있는 형식으로 결과를 반환합니다.
이를 통해 AI 도구는 다음과 같은 작업을 수행할 수 있습니다:
- Kubernetes 리소스 쿼리 (Query)
- kubectl 명령 실행
- 자연어 상호작용을 통한 Kubernetes 클러스터 관리
- Kubernetes 리소스 상태 진단 및 해석
Kubernetes 클러스터의 kubeconfig 파일을 준비한 후 mcpServers에 설정하세요 (src 경로를 사용자의 kubeconfig 경로로 교체하세요):
{
"mcpServers": {
"kubernetes": {
...
kubectl 설치
kubectl이 아직 설치되어 있지 않다면 설치하고 PATH에 추가하세요. 예시는 다음과 같습니다:
# Linux용
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
# MacOS용
...
helm 설치
helm이 아직 설치되어 있지 않다면 설치하고 PATH에 추가하세요. 예시는 다음과 같습니다:
curl -sSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
Claude Desktop, Cursor, ChatGPT Copilot, GitHub Copilot 및 기타 지원되는 AI 클라이언트에서 MCP 서버를 설정하세요. 예시는 다음과 같습니다:
{
"mcpServers": {
"kubernetes": {
...
환경 변수:
KUBECONFIG
: kubeconfig 파일의 경로, 예: /home/<username>/.kube/config
.USE_LEGACY_TOOLS
: 통합된 call_kubectl 도구 대신 여러 개의 특화된 kubectl 도구들을 사용하려면 true로 설정합니다 (기본값: false).
명령줄 인자 (Command line arguments):
./mcp-kubernetes 사용법:
--access-level string 액세스 수준 (readonly, readwrite, 또는 admin) (기본값 "readonly")
--additional-tools string 지원할 추가 도구의 쉼표로 구분된 목록 (kubectl은 항상 활성화되어 있습니다). 사용 가능: helm, cilium, hubble
...
기본적으로 mcp-kubernetes는 단일 통합 call_kubectl을 사용합니다.
모든 kubectl 작업을 하나의 도구 인터페이스로 통합하는 도구입니다. 이는 전체 기능을 유지하면서도 컨텍스트 소비 (context consumption)를 크게 줄여줍니다.
여러 개의 특화된 도구(6-7개의 개별 도구)를 사용하는 레거시 모드 (legacy mode)를 사용하려면 다음 환경 변수를 설정하세요:
{
"mcpServers": {
"kubernetes": {
...
--access-level 플래그는 허용되는 작업을 제어합니다:
readonly (기본값): 읽기 작업만 허용됩니다 (get, describe, logs 등)
readwrite: 읽기 및 쓰기 작업이 허용됩니다 (create, delete, apply 등)
admin: 관리자 작업(cordon, drain, taint 등)을 포함한 모든 작업이 허용됩니다
도구와 작업은 액세스 레벨 (access level)에 따라 등록 시점에 필터링되므로, AI 어시스턴트는 실제로 사용할 수 있는 작업만 보게 됩니다.
설정 예시:
// 읽기 전용 액세스 (기본값)
{
"mcpServers": {
...
AI 클라이언트에서 Kubernetes 클러스터에 대해 무엇이든 질문해 보세요. MCP 도구는 AI 어시스턴트가 kubectl 작업을 이해하고 사용하는 것을 더 쉽게 만들어 줍니다.
내 Kubernetes 클러스터의 상태는 어떠한가요?
내 nginx pod에 무엇이 잘못되었나요?
production 네임스페이스의 모든 deployment를 보여주세요
...
기본적으로 mcp-kubernetes는 모든 kubectl 작업을 처리하는 단일 통합 call_kubectl 도구를 사용합니다. 이 방식은 레거시 멀티 도구 (multi-tool) 방식에 비해 컨텍스트 소비 (context consumption)를 크게 줄여줍니다.
call_kubectl - kubectl 명령 실행
사용 가능 범위: 모든 액세스 레벨 (액세스 레벨에 따라 작업이 필터링됨)
매개변수 (Parameters):
command:
: 'kubectl' 접두사를 포함하여 실행할 전체 kubectl 명령 (예: "kubectl get pods -n default", "kubectl apply -f deployment.yaml")
예시 (Examples):
pod 가져오기 명령: "kubectl get pods -n default"
설정 적용 명령: "kubectl apply -f deployment.yaml"
deployment 스케일링 명령: "kubectl scale deployment nginx --replicas=3"
USE_LEGACY_TOOLS=true일 때
, mcp-kubernetes 서버는 관련 작업을 하나로 묶은 여러 가지 특화된 kubectl 도구들을 제공합니다. 도구는 사용자의 액세스 권한 수준에 따라 자동으로 필터링됩니다.
kubectl_resources - Kubernetes 리소스 관리
사용 가능 권한: readonly, readwrite, admin
Kubernetes 리소스에 대한 CRUD (Create, Read, Update, Delete) 작업 및 노드 관리를 처리합니다. readonly 모드에서는 get 및 describe 작업만 지원합니다. 노드 작업 (cordon, uncordon, drain, taint)은 admin 모드에서만 사용할 수 있습니다.
매개변수 (Parameters):
operation : 수행할 작업 (get, describe, create, delete, apply, patch, replace, cordon, uncordon, drain, taint)
resource : 리소스 유형 (예: pods, deployments, services, nodes) 또는 파일 기반 작업의 경우 빈 값
args : 리소스 이름, 네임스페이스(namespace), 플래그(flag)와 같은 추가 인자
예시 (Examples):
# 모든 pod 가져오기
operation: "get"
resource: "pods"
...
kubectl_workloads - 워크로드 배포 관리
사용 가능 권한: readwrite, admin
스케일링 (scaling) 및 롤아웃 (rollouts)을 포함한 배포 생명주기 작업을 관리합니다.
매개변수 (Parameters):
operation : 수행할 작업 (run, expose, scale, autoscale, rollout)
resource : 롤아웃 작업의 경우, 서브커맨드 (status, history, undo, restart, pause, resume)
args : 추가 인자
예시 (Examples):
# 배포 스케일링
operation: "scale"
resource: "deployment"
...
kubectl_metadata - 리소스 메타데이터 관리
사용 가능 권한: readwrite, admin
리소스의 레이블 (labels), 어노테이션 (annotations) 및 기타 메타데이터를 업데이트합니다.
매개변수 (Parameters):
operation : 수행할 작업 (label, annotate, set)
resource : 리소스 유형
args : 리소스 이름 및 메타데이터 변경 사항
예시 (Examples):
# 레이블 추가
operation: "label"
resource: "pods"
...
kubectl_diagnostics - 리소스 디버깅 및 모니터링
사용 가능 권한: readonly, readwrite, admin
디버깅 및 모니터링 기능을 제공합니다.
매개변수 (Parameters):
operation
: 수행할 작업 (logs, events, top, exec, cp)
resource
: 리소스 유형 또는 특정 리소스
args
: 추가 인자 (Additional arguments)
예시 (Examples):
# 로그 보기 (View logs)
operation: "logs"
resource: ""
...
kubectl_cluster - 클러스터 정보 보기
사용 가능 권한 (Available in): readonly, readwrite, admin
클러스터 수준의 정보 및 API 디스커버리 (API discovery)를 제공합니다.
매개변수 (Parameters):
operation
: 수행할 작업 (cluster-info, api-resources, api-versions, explain)
resource
: explain 작업 시, 문서화할 리소스
args
: 추가 플래그 (Additional flags)
예시 (Examples):
# 클러스터 정보 가져오기 (Get cluster info)
operation: "cluster-info"
resource: ""
...
kubectl_config - 설정 및 보안
사용 가능 권한 (Available in): readonly, readwrite, admin
설정 검증 (Configuration validation), 보안 작업, 그리고 kubectl 컨텍스트 (context) 관리를 처리합니다. readonly 모드에서는 diff, auth can-i, 그리고 읽기 전용 설정 작업을 지원합니다.
매개변수 (Parameters):
operation
: 수행할 작업 (diff, auth, certificate, config)
resource
: auth/certificate/config 작업을 위한 서브커맨드 (Subcommand)
args
: 작업별 특정 인자 (Operation-specific arguments)
예시 (Examples):
# 권한 확인 (Check permissions)
operation: "auth"
resource: "can-i"
...
설정 작업 (Config Operations):
current-context
: 현재 컨텍스트 표시 (readonly, readwrite, admin)
get-contexts
: 사용 가능한 모든 컨텍스트 목록 표시 (readonly, readwrite, admin)
use-context
: 다른 컨텍스트로 전환 (readwrite, admin 전용)
call_helm - Helm 패키지 매니저
사용 가능 조건 (Available when): --additional-tools=helm이 지정된 경우
Kubernetes 애플리케이션 관리를 위한 Helm 명령어를 실행합니다.
매개변수 (Parameters):
command
: 실행할 helm 명령어
예시 (Example):
command: "list --all-namespaces"
call_cilium - Cilium CNI 명령어
사용 가능 조건 (Available when): --additional-tools=cilium이 지정된 경우
네트워크 정책 (Network policies) 및 관측성 (Observability)을 위한 Cilium 명령어를 실행합니다.
매개변수 (Parameters):
command
: 실행할 cilium 명령어
예시 (Example):
command: "status"
call_hubble - Hubble 관찰성 (observability) 명령어
사용 가능 조건: --additional-tools=hubble이 지정된 경우
Cilium이 활성화된 클러스터에서 네트워크 모니터링 및 디버깅을 위해 Hubble 명령어를 실행합니다.
매개변수 (Parameters):
command
: 실행할 hubble 명령어
예시 (Example):
command: "status"
command: "observe observe --namespace backend-jobs --from-label 'app=web'"
command: "list nodes"
텔레메트리 (Telemetry) 수집은 기본적으로 활성화되어 있습니다.
수집을 원하지 않을 경우, 환경 변수 KUBERNETES_MCP_COLLECT_TELEMETRY=false를 설정하십시오.
mcp-kubernetes 서버는 OpenTelemetry 프로토콜 (OTLP)을 사용하여 텔레메트리 데이터를 내보내는 것을 지원합니다. OTLP 엔드포인트를 구성하여 모든 OpenTelemetry 호환 백엔드로 트레이스 (traces)를 보낼 수 있습니다:
{
"mcpServers": {
"kubernetes": {
...
MCP 서버의 요청(requests) 및 응답(responses)을 검사하는 방법:
npx @modelcontextprotocol/inspector <'mcp-kubernetes' 바이너리 경로>
이 프로젝트는 기여와 제안을 환영합니다. 대부분의 기여에는 귀하가 기여를 사용할 권리를 가지고 있으며 실제로 권한을 부여한다는 것을 선언하는 기여자 라이선스 동의서 (Contributor License Agreement, CLA)에 동의해야 합니다. 자세한 내용은 https://cla.opensource.microsoft.com 을 방문하십시오.
풀 리퀘스트 (pull request)를 제출하면, CLA 봇이 귀하가 CLA를 제공해야 하는지 여부를 자동으로 판단하고 PR에 적절하게 표시(예: 상태 확인, 댓글)합니다. 봇이 제공하는 지침을 따르기만 하면 됩니다. 이 작업은 당사의 CLA를 사용하는 모든 리포지토리(repos)에 대해 단 한 번만 수행하면 됩니다.
이 프로젝트는 Microsoft 오픈 소스 행동 강령 (Open Source Code of Conduct)을 채택했습니다. 자세한 내용은 행동 강령 FAQ를 참조하거나 추가 질문 또는 의견이 있는 경우 opencode@microsoft.com 으로 문의하십시오.
이 프로젝트에는 프로젝트, 제품 또는 서비스에 대한 상표나 로고가 포함되어 있을 수 있습니다. Microsoft 상표 또는 로고의 승인된 사용은 Microsoft의 상표 및 브랜드 가이드라인 (Trademark & Brand Guidelines)을 준수해야 하며 이에 따라야 합니다. 이 프로젝트의 수정된 버전에서 Microsoft 상표 또는 로고를 사용하는 것은 혼란을 야기하거나 Microsoft의 후원을 암시해서는 안 됩니다. 제3자의 상표 또는 로고를 사용하는 모든 행위는 해당 제3자의 정책을 따릅니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 GitHub AI Tools의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기