Inspektor Gadget MCP Server

Inspektor Gadget MCP 服务

Inspektor Gadget MCP 服务通过 Model Context Protocol (MCP)，将 Inspektor Gadget 的底层内核可观测性与大模型连接起来。它将原始的 eBPF 遥测数据——DNS 跟踪、TCP 连接、进程执行、文件活动、系统调用等——转化为可操作的情报，供 AI Agent 推理分析，从而直接通过 IDE 或 AI 聊天界面实现数据驱动的根因分析。

flowchart LR
    User["👤 User<br/>(IDE / Chat)"]
    LLM["🤖 LLM"]
    MCP["⚙️ IG MCP Server"]
    IG["🔍 Inspektor Gadget"]
    Kernel["🐧 Linux Kernel<br/>(eBPF)"]
    K8s["☸️ Kubernetes<br/>Cluster"]

    User -- prompt --> LLM
    LLM -- MCP tool calls --> MCP
    MCP -- run gadgets --> IG
    IG -- eBPF hooks --> Kernel
    Kernel -. telemetry .-> IG
    IG -. enriched data .-> MCP
    MCP -. structured JSON .-> LLM
    LLM -- analysis & RCA --> User
    IG -- metadata --> K8s

功能

• AI 驱动的根因分析 — 大模型会关联多个 gadget 收集的底层内核数据，精准定位问题，以证据取代猜测。
• 完整的 gadget 生命周期管理 — 无需离开 AI 聊天界面，即可部署、运行、停止 Inspektor Gadget 工具并获取结果。
• 前台和后台模式 — 在前台运行 gadget，快速调试；或在后台运行，实现持续可观测性，并在需要时获取结果。
• 动态注册工具 — 每个 gadget 都会成为独立的 MCP 工具（例如 gadget_trace_dns、gadget_trace_tcp），其参数、字段说明和筛选条件均根据 gadget 元数据自动生成。
• 只读模式 — 将服务限制为非破坏性操作，确保在生产环境中安全使用。
• 灵活部署 — 可作为本地二进制文件（stdio）或 Docker 容器运行，也可直接部署到 Kubernetes 集群中（HTTP 传输）。

背景

可观测性缺口

Kubernetes 故障排查并不容易。传统工具提供日志、指标和高层级资源状态，但当网络、系统调用或内核层面出现问题时，_可见的信息_与_实际发生的情况_之间往往存在缺口。

Inspektor Gadget 正是为弥补这一缺口而生。它提供名为 gadgets 的模块化可观测单元——这些 eBPF 程序会挂钩 Linux 内核，实时收集底层遥测数据。Gadget 可以跟踪 DNS 查询、TCP 连接、进程执行、文件打开、信号、OOM 终止、系统调用等，还会为所有数据添加 Kubernetes 元数据（Pod、命名空间、容器、节点）。

LLM 为何改变了局面

这些内核级数据堪称超能力，但也十分_密集_。一次 10 秒的 DNS 跟踪就可能在数十个 Pod 中产生数百条事件。手动筛选原始遥测数据，以关联事件、发现异常并确定根本原因，需要深厚的专业知识和大量时间。

LLM 正是缺失的一环。通过 MCP 暴露 Inspektor Gadget 后，AI Agent 可以：

1. 自主选择合适的 Gadget — 根据问题描述，LLM 会决定要收集哪些遥测数据（DNS 跟踪？TCP 连接？进程执行？），无需你知道该运行哪个 Gadget。
2. 关联多个数据源 — AI 可以运行多个 Gadget，交叉引用它们的输出，并全面还原发生的情况。
3. 执行可靠、以数据为依据的根因分析 — LLM 不再靠猜测，而是以真实的内核级证据为依据进行分析，找出失败的确切 DNS 查询、被拒绝的具体 TCP 连接，或触发 OOM kill 的特定进程。
4. 用通俗语言解释发现 — 将原始 eBPF 输出转化为清晰、可执行的摘要，并提供具体的后续步骤。

sequenceDiagram
    actor User
    participant LLM
    participant MCP as IG MCP Server
    participant IG as Inspektor Gadget
    participant K8s as Kubernetes

    User->>LLM: "DNS is failing for my pod in default namespace"
    activate LLM
    LLM->>MCP: ig_deploy(action: is_deployed)
    MCP-->>LLM: ✅ Deployed
    LLM->>MCP: gadget_trace_dns(namespace: default, duration: 10s)
    MCP->>IG: Run trace_dns gadget
    IG->>K8s: Attach eBPF probes
    K8s-->>IG: DNS events (queries, responses, latencies)
    IG-->>MCP: Enriched telemetry (pod, namespace, container)
    MCP-->>LLM: Structured JSON results
    LLM->>MCP: gadget_trace_dns(namespace: kube-system, duration: 10s)
    MCP->>IG: Run trace_dns on kube-system
    IG-->>MCP: CoreDNS telemetry
    MCP-->>LLM: Structured JSON results
    deactivate LLM
    LLM->>User: 📋 RCA: "NXDOMAIN errors for service.wrong-ns.svc.cluster.local — the service is in a different namespace. Latency is normal (2-5ms), CoreDNS is healthy."

查看实际效果

AI 会选择相关的 Gadget、收集数据并分析结果——整个过程都在一次对话中完成：

https://github.com/user-attachments/assets/0f146943-3bf9-4c4d-90c8-76a101d7a4b4

LLM 会自主运行 gadget_tcpdump 和 gadget_snapshot_socket，捕获 TCP 连接 RESET 事件，然后分析丰富的遥测数据，找出被拒绝的确切连接，并将其与 Pod 和容器元数据关联起来，从而提供精准的根因分析。

快速开始

1. 确保你已安装 Docker，并拥有有效的 kubeconfig 文件
2. 在 IDE 或命令行中配置 MCP 服务 — 设置指南请参阅 INSTALL.md，涵盖 VS Code、GitHub Copilot CLI、Claude Code 以及其他兼容 MCP 的客户端
3. 开始对话：“显示 DNS 流量”、“有没有失败的 TCP 连接？” 或 “部署 Inspektor Gadget”
4. 查看 示例，了解详细的操作演示

安装

IG MCP Server 可通过 Docker、二进制文件安装，也可以直接部署到 Kubernetes 集群中。完整说明、客户端配置（VS Code、Copilot CLI、Claude Code）以及所有配置选项，请参阅安装指南。

可用工具

Inspektor Gadget 生命周期

工具	描述
ig_deploy	在集群上部署、升级、卸载 Inspektor Gadget，或检查其状态

Gadget 管理

工具	描述
ig_gadgets	列出正在运行的 Gadget、获取后台运行结果，或停止 Gadget

Gadget 工具（动态注册）

每个 gadget 都会注册为一个独立的 MCP 工具，前缀为 gadget_，并完整支持参数。可用的 gadget 取决于你的配置：

类别	工具示例	功能
跟踪	gadget_trace_dns、gadget_trace_tcp、gadget_trace_exec、gadget_trace_open、gadget_trace_signal、gadget_trace_bind	捕获实时事件（DNS 查询、TCP 连接、进程执行、文件打开、信号、套接字绑定）
快照	gadget_snapshot_process、gadget_snapshot_socket	获取运行中进程或已打开套接字的瞬时快照
Top	gadget_top_file、gadget_top_tcp、gadget_top_blockio	定期报告资源消耗排名靠前的项目（文件 I/O、TCP 流量、块 I/O）
性能分析	gadget_profile_blockio、gadget_profile_tcprtt	分析块 I/O 延迟或 TCP 往返时间
安全	gadget_trace_capabilities、gadget_advise_seccomp、gadget_audit_seccomp、gadget_trace_lsm	跟踪能力检查、建议或审计 seccomp 配置文件、跟踪 LSM 钩子
高级	gadget_traceloop、gadget_trace_oomkill、gadget_trace_ssl、gadget_deadlock	系统调用飞行记录器、OOM 终止跟踪、SSL/TLS 捕获、死锁检测

每个工具都支持前台（默认）和后台运行模式、字段级输出筛选，并生成结构化 JSON 输出，由大模型自动总结。

**⚠️ 上下文窗口提示：**每个已注册的 MCP 工具都会占用大模型的部分上下文窗口——工具定义、参数架构和字段说明都会计入上限。如果你使用的模型上下文窗口较小，或者想为 gadget 输出和分析留出更多空间，请使用 -gadget-images 仅加载所需的 gadget，而不是通过 Artifact Hub 发现所有可用的 gadget。例如，-gadget-images=trace_dns:latest,trace_tcp:latest 只会注册两个工具，而不是 30 多个。

Gadget 发现

控制可用的 gadget：

• 自动：从 Artifact Hub 发现（-gadget-discoverer=artifacthub）
• 手动：指定确切的 gadget（-gadget-images=trace_dns:latest,trace_tcp:latest）

有关所有配置选项，请参阅 INSTALL.md。

示例

示例	描述	截图
DNS 调试	通过跟踪查询、检测故障和分析延迟模式，排查 DNS 解析问题
了解 Kubernetes	在部署期间使用多个后台运行模式的 gadget 观察集群实时活动
安全可观测性	通过监控进程执行和文件访问模式，检测可疑活动
系统调用记录	记录并重放系统调用序列，以深入调试 Pod 行为

安全说明

• 需要对 kubeconfig 文件具有只读访问权限
• Artifact Hub 发现功能需要网络访问
• 支持 -read-only 模式，以限制为非破坏性操作
• 有关如何以最小权限配置服务，请参阅安全指南

资源

• 📖 文档
• 🔍 示例
• 📋 安装指南
• 🐛 问题
• 💬 Slack
• 🌐 网站
• 📋 故障排查
• 🔒 安全指南
• 🤝 贡献

相关项目

• Inspektor Gadget — 基于 eBPF 的 Linux 和 Kubernetes 可观测性工具
• MCP 规范 — Model Context Protocol

许可证

Apache License 2.0 — 详情请参阅 LICENSE。