Kubeshark

Kubeshark MCP 서버

Kubeshark MCP (모델 컨텍스트 프로토콜) 서버는 Claude Desktop, Cursor 및 기타 MCP 호환 클라이언트와 같은 AI 어시스턴트가 실시간 Kubernetes 네트워크 트래픽을 쿼리할 수 있도록 합니다.

AI 스킬

MCP는 도구를 제공하며, AI 스킬은 에이전트에게 이를 사용하는 방법을 가르칩니다. 스킬은 원시 MCP 기능을 근본 원인 분석, 트래픽 필터링, 포렌식 조사와 같은 도메인별 워크플로우로 전환합니다. 설치 및 사용법은 스킬 README를 참조하십시오.

스킬	설명
network-rca	네트워크 근본 원인 분석 — PCAP 및 분석 경로를 통한 스냅샷 기반 회고적 조사
kfl	KFL2 필터 전문가 — 지원되는 모든 프로토콜에서 트래픽 쿼리 작성, 디버깅 및 최적화

기능

• L7 API 트래픽 분석: HTTP, gRPC, Redis, Kafka, DNS 트랜잭션 쿼리
• L4 네트워크 흐름: 트래픽 통계가 포함된 TCP/UDP 흐름 보기
• 클러스터 관리: Kubeshark 배포 시작/중지 (안전 제어 포함)
• PCAP 스냅샷: 네트워크 캡처 생성 및 내보내기
• 내장 프롬프트: 일반적인 분석 작업을 위해 사전 구성된 프롬프트

설치

1. Kubeshark CLI 설치

# macOS
brew install kubeshark

# Linux
sh <(curl -Ls https://kubeshark.com/install)

# Windows (PowerShell)
choco install kubeshark

또는 GitHub 릴리스에서 다운로드하십시오.

2. Claude Desktop 구성

Claude Desktop 구성에 추가하십시오:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

기본값 (kubectl 액세스 / kube 컨텍스트 필요)

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp"]
    }
  }
}

명시적 kubeconfig 경로 사용:

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp", "--kubeconfig", "/path/to/.kube/config"]
    }
  }
}

URL 모드 (kubectl 불필요)

머신에 kubectl 액세스 또는 kube 컨텍스트가 없을 때 사용하십시오. 기존 Kubeshark 배포에 직접 연결합니다:

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp", "--url", "https://kubeshark.example.com"]
    }
  }
}

게이트 허브(AUTH_ENABLED=true)의 경우, URL 모드는 토큰을 발행할 수 없으므로(kube 액세스 없음) --token (또는 KUBESHARK_HUB_TOKEN 환경 변수)를 통해 명시적으로 제공하십시오. 클러스터 액세스 권한이 있는 머신에서 발행하십시오:

kubectl create token kubeshark-cli -n <release-namespace> --audience kubeshark-hub

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp", "--url", "https://kubeshark.example.com", "--token", "<token>"]
    }
  }
}

토큰은 수명이 짧으며(~1시간) URL 모드는 자동 갱신할 수 없습니다. 만료되면 서버는 명확한 401 ... token expired/invalid 메시지를 보고하므로 다시 발행하고 다시 시작하십시오. 프록시 모드(기본값, kube 액세스 포함)는 kubeshark-cli 토큰을 자동으로 발행하고 자동 갱신하므로 장기 실행 세션이 만료되지 않습니다.

파괴적 작업 포함

{
  "mcpServers": {
    "kubeshark": {
      "command": "kubeshark",
      "args": ["mcp", "--allow-destructive", "--kubeconfig", "/path/to/.kube/config"]
    }
  }
}

3. 구성 생성

CLI를 사용하여 구성을 생성하십시오:

kubeshark mcp --mcp-config --url https://kubeshark.example.com

사용 가능한 도구

트래픽 분석 (모든 모드)

도구	설명
list_workloads	관찰된 트래픽이 있는 파드, 서비스, 네임스페이스 나열
list_api_calls	KFL 필터링을 사용하여 L7 API 트랜잭션 쿼리
get_api_call	특정 API 호출에 대한 자세한 정보 가져오기
get_api_stats	집계된 API 통계 가져오기
list_l4_flows	L4 (TCP/UDP) 네트워크 흐름 나열
get_l4_flow_summary	L4 연결 요약 가져오기
list_snapshots	모든 PCAP 스냅샷 나열
create_snapshot	새 PCAP 스냅샷 생성
get_dissection_status	L7 프로토콜 파싱 상태 확인
enable_dissection	L7 프로토콜 분석 활성화
disable_dissection	L7 프로토콜 분석 비활성화

클러스터 관리 (프록시 모드만 해당)

도구	설명	필요 조건
check_kubeshark_status	Kubeshark 실행 여부 확인	-
start_kubeshark	클러스터에 Kubeshark 배포	--allow-destructive
stop_kubeshark	클러스터에서 Kubeshark 제거	--allow-destructive

사용 가능한 프롬프트

프롬프트	설명
analyze_traffic	API 트래픽 패턴 분석 및 문제 식별
find_errors	API 오류 및 실패 찾기 및 요약
trace_request	마이크로서비스를 통한 요청 경로 추적
show_topology	서비스 통신 토폴로지 표시
latency_analysis	지연 시간 패턴 분석 및 느린 엔드포인트 식별
security_audit	보안 문제에 대한 트래픽 감사
compare_traffic	기간 간 트래픽 패턴 비교
debug_connection	서비스 간 연결 문제 디버깅

대화 예시

User: Show me all HTTP 500 errors in the last hour

Claude: I'll query the API traffic for 500 errors.
[Calling list_api_calls with kfl="http and response.status == 500"]

Found 12 HTTP 500 errors:
1. POST /api/checkout -> payment-service (500)
   Time: 10:23:45 | Latency: 2340ms
...

User: What services are communicating with the database?

Claude: Let me check the L4 flows to the database.
[Calling list_l4_flows with dst_filter="postgres"]

Found 5 services connecting to postgres:5432:
- orders-service: 456KB transferred
- users-service: 123KB transferred
...

CLI 옵션

옵션	설명
--url	Kubeshark Hub에 대한 직접 URL
--token	게이트 허브에 대한 --url 모드용 Hub SA/베어러 토큰 (또한 KUBESHARK_HUB_TOKEN); 토큰을 발행하고 자동 갱신하는 프록시 모드에서는 무시됨
--kubeconfig	kubeconfig 파일 경로
--allow-destructive	시작/중지 작업 활성화
--list-tools	사용 가능한 도구 나열 및 종료
--mcp-config	Claude Desktop 구성 JSON 출력

KFL (Kubeshark 필터 언어)

KFL 구문을 사용하여 트래픽 쿼리:

# HTTP requests to a specific path
http and request.path == "/api/users"

# Errors only
response.status >= 400

# Specific source pod
src.pod.name == "frontend-.*"

# Multiple conditions
http and src.namespace == "default" and response.status == 500

MCP 레지스트리

Kubeshark는 각 릴리스 시 자동으로 MCP 레지스트리에 게시됩니다.

이 디렉터리의 server.json는 참조 파일입니다. 실제 레지스트리 메타데이터(버전, SHA256 해시)는 릴리스 워크플로 중에 자동 생성됩니다. 자세한 내용은 .github/workflows/release.yml를 참조하십시오.

링크

• 문서
• GitHub
• 웹사이트
• MCP 레지스트리

라이선스

Apache-2.0