Kubeshark

官方

MCP 存取叢集範圍的 L4 與 L7 網路流量、封包、API 及完整負載。

GitHub

12k

你可以用 Kubeshark MCP 做什麼？

使用 KFL 篩選器查詢 L7 API 交易 — 透過 list_api_calls 尋找符合狀態碼或路徑等條件的 HTTP、gRPC、Redis、Kafka 或 DNS 請求。
詳細檢查特定 API 呼叫 — 使用 get_api_call 擷取單一交易的完整請求/回應資料。
取得彙總的 API 統計資料 — 透過 get_api_stats 總結流量模式、錯誤率或延遲分佈。
檢視 L4 網路流量與摘要 — 經由 list_l4_flows 與 get_l4_flow_summary 列出 TCP/UDP 連線並取得連線概覽。
建立與管理 PCAP 快照 — 使用 create_snapshot 與 list_snapshots 擷取網路流量以供離線分析。
控制 L7 協定剖析 — 透過 enable_dissection 與 disable_dissection 依需求啟用或停用深度協定解析。

文件

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 Releases 下載。

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"]
    }
  }
}

針對受控管的 Hub（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`	列出具有觀測流量的 Pod、服務、命名空間
`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`	針對受控管 Hub 的 `--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。

連結

授權

Apache-2.0