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（模型上下文协议）服务器使 AI 助手（如 Claude Desktop、Cursor 及其他 MCP 兼容客户端）能够查询实时 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