MCPSpy - 使用 eBPF 监控 MCP 🕵️✨

███╗   ███╗ ██████╗██████╗ ███████╗██████╗ ██╗   ██╗
████╗ ████║██╔════╝██╔══██╗██╔════╝██╔══██╗╚██╗ ██╔╝
██╔████╔██║██║     ██████╔╝███████╗██████╔╝ ╚████╔╝ 
██║╚██╔╝██║██║     ██╔═══╝ ╚════██║██╔═══╝   ╚██╔╝  
██║ ╚═╝ ██║╚██████╗██║     ███████║██║        ██║   
╚═╝     ╚═╝ ╚═════╝╚═╝     ╚══════╝╚═╝        ╚═╝   

概述

MCPSpy 是一款功能强大的命令行工具，它利用 eBPF（扩展的伯克利数据包过滤器） 技术，在内核级别监控 模型上下文协议（MCP） 通信。通过挂钩到底层系统调用，它可以实时查看 MCP 客户端和服务器之间交换的 JSON-RPC 2.0 消息。

模型上下文协议支持三种传输协议进行通信：

• Stdio：通过标准输入/输出流进行通信
• 可流式 HTTP：直接的 HTTP 请求/响应通信，带有服务器发送事件
• SSE（服务器发送事件）：基于 HTTP 的流式通信（已弃用）

MCPSpy 支持对 Stdio 和 HTTP/HTTPS 传输的监控（包括服务器发送事件），从而全面覆盖 MCP 通信通道。

为什么选择 MCPSpy？

模型上下文协议正逐渐成为 AI 工具集成的标准，但要理解其内部运作机制却颇具挑战性。MCPSpy 通过以下方式解决了这一问题：

• 🔒 安全分析：监控传输的数据，检测 PII 泄露，并审计工具执行情况
• 🛡️ 提示注入检测：使用机器学习模型实时检测提示注入和越狱尝试
• 🐛 调试：通过查看实际的消息流来排查 MCP 集成中的问题
• 📊 性能监控：跟踪消息模式并识别瓶颈
• 🔍 合规性：确保 MCP 通信符合监管要求
• 🎓 学习：通过观察真实的通信过程来理解 MCP 的工作原理

安装

先决条件

• Linux 内核版本 5.15 或更高
• root 权限（eBPF 所需）

下载预编译二进制文件（自动检测操作系统 + 架构）

从 发布页面 下载最新版本：

# 设置平台感知的二进制文件名
BIN="mcpspy-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')"

# 下载正确的二进制文件
wget "https://github.com/alex-ilgayev/mcpspy/releases/latest/download/${BIN}"

# 使其可执行并移动到 PATH 中的目录
chmod +x "${BIN}"
sudo mv "${BIN}" /usr/local/bin/mcpspy

✅ 注意：目前支持的平台：linux-amd64、linux-arm64

从源代码构建

安装依赖项

首先，安装所需的系统依赖项：

sudo apt-get update
# 安装构建工具和 eBPF 依赖项
sudo apt-get install -y clang clang-format llvm make libbpf-dev build-essential
# 安装 Python 3 和 pip（用于端到端测试）
sudo apt-get install -y python3 python3-pip python3-venv
# 安装 docker 和 buildx（如果尚未安装）
sudo apt-get install -y docker.io docker-buildx

安装 Go

MCPSpy 需要 Go 1.24 或更高版本。可以使用以下方法之一安装 Go：

选项 1：从官方 Go 网站安装（推荐）

# 下载并安装 Go 1.24.1（可根据需要调整版本）
wget https://go.dev/dl/go1.24.1.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.1.linux-amd64.tar.gz

# 将 Go 添加到 PATH 中（将其添加到 ~/.bashrc 或 ~/.profile 以保持永久生效）
export PATH=$PATH:/usr/local/go/bin

选项 2：通过 snap 安装

sudo snap install go --classic

构建 MCPSpy

克隆仓库并构建 MCPSpy：

# 克隆仓库
git clone https://github.com/alex-ilgayev/mcpspy.git
cd mcpspy

# 构建项目
make all

Docker

# 构建 Docker 镜像
make image
# 或者拉取最新镜像
docker pull ghcr.io/alex-ilgayev/mcpspy:latest
# 或者拉取特定版本的镜像
docker pull ghcr.io/alex-ilgayev/mcpspy:v0.1.0

# 运行容器
docker run --rm -it --privileged ghcr.io/alex-ilgayev/mcpspy:latest

Kubernetes

MCPSpy 可以部署在 Kubernetes 集群中，用于监控来自 LangFlow、LangGraph 等使用模型上下文协议的 AI/LLM 服务的 MCP 流量。

# 将 MCPSpy 部署为 DaemonSet
kubectl apply -f https://raw.githubusercontent.com/alex-ilgayev/mcpspy/main/deploy/kubernetes/mcpspy.yaml

Kubernetes 中的实际应用场景

1. 监控 LangFlow/LangGraph 部署

   • 观察 LangFlow/LangGraph 与 AI 服务之间的 MCP 流量
   • 调试复杂 AI 工作流中的集成问题
   • 审计 AI 交互以确保安全性和合规性

2. AI 服务监控

   • 跟踪与远程和本地 MCP 服务器的交互
   • 识别 AI 服务调用中的性能瓶颈
   • 检测 AI 通信中潜在的 data 泄露

3. 开发和测试

   • 在容器化环境中测试 MCP 实现
   • 在生产部署前验证 AI 服务集成
   • 确保不同环境下的行为一致性

有关在 Kubernetes 中监控 AI 服务的详细说明和实际示例，请参阅 Kubernetes 使用指南。

使用方法

基本用法

# 开始监控 MCP 通信（默认为 TUI 模式）
sudo mcpspy

# 以静态控制台输出开始监控（禁用 TUI）
sudo mcpspy --tui=false

# 开始监控并将输出保存到 JSONL 文件
sudo mcpspy -o output.jsonl

# 使用 Ctrl+C（或 TUI 模式下的 'q'）停止监控

提示注入检测

MCPSpy 包含可选的实时提示注入检测功能，使用 HuggingFace 的推理 API。启用后，它会分析 MCP 工具调用，以检测潜在的注入攻击和越狱尝试。

检测范围：

1. 基于请求的注入：检测工具调用参数中的恶意提示
2. 基于响应的注入：检测工具响应中可能操纵代理的恶意内容

# 使用 HuggingFace token 启用安全扫描
sudo mcpspy --security --hf-token=hf_xxxxx

# 使用自定义检测模型
sudo mcpspy --security --hf-token=hf_xxxxx --security-model=protectai/deberta-v3-base-prompt-injection-v2

# 调整检测阈值（默认：0.5）
sudo mcpspy --security --hf-token=hf_xxxxx --security-threshold=0.7

# 同步运行分析（阻塞直到分析完成）
sudo mcpspy --security --hf-token=hf_xxxxx --security-async=false

安全 CLI 标志：

支持的模型：

• protectai/deberta-v3-base-prompt-injection-v2（默认，公开可访问）
• meta-llama/Llama-Prompt-Guard-2-86M（已在 HF 推理 API 上弃用）

当检测到潜在的注入时，MCPSpy 会显示一个安全警报，包含风险等级（低/中/高/严重）、类别以及被分析的内容。

输出格式

TUI 模式（默认）

MCPSpy 默认以交互式终端 UI 模式运行。TUI 提供：

• 可滚动的交互式表格视图
• 详细的消息检查（按 Enter 键）
• 按传输方式、类型和执行者进行过滤
• 多种密度模式，适用于不同尺寸的屏幕
• 实时统计信息

静态控制台输出

当使用 --tui=false 运行时：

12:34:56.789 python[12345] → python[12346] REQ 工具/调用（get_weather） 执行工具
12:34:56.890 python[12346] → python[12345] RESP 成功

JSONL 输出

Stdio 传输 - 请求：

{
  "timestamp": "2024-01-15T12:34:56.789Z",
  "transport_type": "stdio",
  "stdio_transport": {
    "from_pid": 12345,
    "from_comm": "python",
    "to_pid": 12346,
    "to_comm": "python"
  },
  "type": "request",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "New York" }
  },
  "error": {},
  "raw": "{...}"
}

Stdio 传输 - 响应：

{
  "timestamp": "2024-01-15T12:34:56.890Z",
  "transport_type": "stdio",
  "stdio_transport": {
    "from_pid": 12346,
    "from_comm": "python",
    "to_pid": 12345,
    "to_comm": "python"
  },
  "type": "response",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "纽约天气：20°C"
      }
    ],
    "isError": false
  },
  "error": {},
  "request": {
    "type": "request",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "get_weather",
      "arguments": { "city": "New York" }
    },
    "error": {}
  },
  "raw": "{...}"
}

HTTP/HTTPS 传输 - 请求：

{
  "timestamp": "2024-01-15T12:34:56.789Z",
  "transport_type": "http",
  "http_transport": {
    "pid": 47837,
    "comm": "python",
    "host": "127.0.0.1:12345",
    "is_request": true
  },
  "type": "request",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "New York" }
  },
  "error": {},
  "raw": "{...}"
}

HTTP/HTTPS 传输 - 响应：

{
  "timestamp": "2024-01-15T12:34:56.890Z",
  "transport_type": "http",
  "http_transport": {
    "pid": 47837,
    "comm": "python",
    "host": "127.0.0.1:12345"
  },
  "type": "response",
  "id": 7,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "纽约天气：20°C"
      }
    ],
    "isError": false
  },
  "error": {},
  "request": {
    "type": "request",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "get_weather",
      "arguments": { "city": "New York" }
    },
    "error": {}
  },
  "raw": "{...}"
}

架构

MCPSpy 采用事件驱动架构，并使用发布-订阅模式来解耦组件，从而实现可扩展性。该系统由多个组件组成，这些组件通过中央事件总线进行通信：

1. 事件总线 (pkg/bus/)

• 使用发布-订阅模式的中央通信枢纽
• 支持异步事件处理
• 使用 github.com/asaskevich/EventBus 库

2. eBPF 程序 (bpf/)

• 钩子到内核函数 vfs_read 和 vfs_write 中，用于 stdio 传输
• 钩子到 TLS 库函数（SSL_read, SSL_write）中，用于 HTTP/HTTPS 传输
• 通过检测 JSON 模式来过滤潜在的 MCP 流量
• 通过环形缓冲区将事件发送到用户空间
• 通过早期过滤实现最小性能影响

3. eBPF 加载器 (pkg/ebpf/)

• 管理 eBPF 程序及其资源的生命周期
• 使用 cilium/ebpf 库将预编译的 eBPF 对象加载到内核中
• 将来自内核空间的原始二进制事件转换为结构化的 Go 数据类型
• 将事件发布到事件总线，以便下游处理

4. HTTP 会话管理器 (pkg/http/)

• 订阅事件总线上的 TLS 相关事件
• 管理 HTTP/HTTPS 会话，并关联请求和响应对
• 处理 TLS 负载的拦截和解析
• 支持分块传输编码和服务器发送事件 (SSE)
• 从碎片化的 TLS 数据中重建完整的 HTTP 消息
• 将重建的 HTTP 正文发布到事件总线，以供 MCP 解析

5. MCP 协议解析器 (pkg/mcp/)

• 订阅来自事件总线的数据事件（stdio 和 HTTP TLS 负载）
• 验证 JSON-RPC 2.0 消息格式
• 解析 MCP 特定的方法和参数
• 将读操作和写操作关联成单个 MCP 消息（适用于 stdio 传输）
• 同时支持 stdio 和 HTTP/HTTPS 传输（包括 SSE）
• 将解析后的 MCP 消息发布到事件总线

6. 输出处理器 (pkg/output/)

• 订阅来自事件总线的 MCP 消息事件
• 控制台显示带颜色的格式化输出
• JSONL 输出，便于程序化分析
• 实时统计跟踪

7. 事件记录器 (pkg/eventlogger/)

• 订阅事件总线上的所有事件，用于调试
• 提供系统中事件流的详细日志记录
• 不同事件类型的可配置日志级别

8. 安全分析器 (pkg/security/)

• 可选组件，用于实时提示注入检测
• 订阅来自事件总线的 MCP 消息事件
• 分析高风险方法（tools/call, resources/read, prompts/get）
• 使用 HuggingFace 推理 API，并可配置机器学习模型
• 在检测到注入时发布安全警报
• 支持异步和同步分析模式

开发

构建

# 生成 eBPF 绑定并构建
make all

# 构建 Docker 映像
make image

测试

MCPSpy 包含全面的端到端测试，可模拟不同传输方式下的真实 MCP 通信：

# （可选）设置测试环境
make test-e2e-setup

# 运行所有测试（需要 root 权限）
make test-e2e

# 运行单个传输方式的测试
make test-e2e-stdio   # 测试 stdio 传输
make test-e2e-https   # 测试 HTTP/HTTPS 传输

测试套件包括：

• 用于 stdio 和 HTTP 传输的 MCP 服务器和客户端模拟器
• 根据预期输出验证消息
• 覆盖多种消息类型
• SSL/TLS 加密的 HTTP 通信测试

限制

• FS 事件缓冲区大小：每个消息限制为 16KB。这意味着 缓冲区大小 超过 16KB 的 MCP 消息将被遗漏或忽略。
• 由多个消息组成的 FS 事件：MCPSpy 目前不支持重构跨多个 read 或 write 系统调用拆分的 MCP 消息。因此，如果 MCP 消息大于单次系统调用使用的缓冲区大小，可能会被遗漏或忽略。
• 对于 stdio 传输的 inode 冲突：inode 号码仅在单个文件系统内是唯一的。如果监控跨多个文件系统或挂载命名空间的进程，理论上可能存在 inode 冲突，但在基于管道的 stdio 通信中这种情况很少发生。
• 平台：仅支持 Linux（内核 5.15+）。

代理工作流设置

MCPSpy 支持与 Claude Code 等 AI 编程助手一起开发。由于 mcpspy 需要 root 权限才能执行 eBPF 操作，您需要配置无密码 sudo，以实现自动化测试执行。

配置 Sudoers 以实现无密码执行

创建一个 sudoers 规则，允许您的用户无需输入密码即可运行 mcpspy。端到端测试会使用位于 build/mcpspy-linux-amd64（或在 ARM 上为 build/mcpspy-linux-arm64）的二进制文件：

# 选项 1：使用 visudo（打开编辑器）
sudo visudo -f /etc/sudoers.d/mcpspy
# 添加以下行（替换 YOUR_USERNAME 并根据需要调整路径）：
# YOUR_USERNAME ALL=(ALL) NOPASSWD: /home/YOUR_USERNAME/mcpspy/build/mcpspy-linux-amd64, /home/YOUR_USERNAME/mcpspy/.worktrees/*/build/mcpspy-linux-amd64

# 选项 2：一行命令（替换 YOUR_USERNAME 和路径）
echo 'YOUR_USERNAME ALL=(ALL) NOPASSWD: /home/YOUR_USERNAME/mcpspy/build/mcpspy-linux-amd64, /home/YOUR_USERNAME/mcpspy/.worktrees/*/build/mcpspy-linux-amd64' | sudo tee /etc/sudoers.d/mcpspy && sudo chmod 440 /etc/sudoers.d/mcpspy

.worktrees/* 模式允许从 git 工作树中无密码执行。请注意，sudoers 中的 * 不匹配 /，因此需要同时使用这两种模式。

配置完成后，请验证是否生效：

sudo /path/to/build/mcpspy-linux-amd64 --help  # 不应提示输入密码

这样，AI 助手就可以运行需要 sudo 权限进行 eBPF 操作的端到端测试（make test-e2e）。

贡献

我们欢迎您的贡献！请随时提出问题或提交拉取请求。

许可证

• 用户态代码（主要为 Go）：Apache 2.0（参见 LICENSE）
• eBPF C 程序（bpf/*）：GPL-2.0-only（参见 LICENSE-BPF）

MCPSpy 快速上手指南

MCPSpy 是一款基于 eBPF 技术的命令行工具，用于在内核层面实时监控模型上下文协议（MCP）的通信流量。它支持 Stdio 和 HTTP/HTTPS 传输协议，帮助开发者调试集成、分析安全风险及监控性能。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux (内核版本 5.15 或更高)
• 权限要求：需要 Root 权限（eBPF 程序加载必需）
• 架构支持：amd64 (x86_64) 或 arm64 (aarch64)

注意：目前仅支持 Linux 平台。

安装步骤

您可以选择下载预编译二进制文件（推荐）或通过源码构建。

方法一：下载预编译二进制文件

以下命令会自动检测您的操作系统和架构，下载对应的最新版本并安装到系统路径：

# 设置平台相关的二进制文件名
BIN="mcpspy-$(uname -s | tr '[:upper:]' '[:lower:]')-$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')"

# 下载对应的二进制文件
wget "https://github.com/alex-ilgayev/mcpspy/releases/latest/download/${BIN}"

# 赋予执行权限并移动到 PATH 目录
chmod +x "${BIN}"
sudo mv "${BIN}" /usr/local/bin/mcpspy

方法二：从源码构建

如果您需要自定义构建或贡献代码，请按以下步骤操作：

1. 安装系统依赖：

   sudo apt-get update
   # 安装构建工具及 eBPF 依赖
   sudo apt-get install -y clang clang-format llvm make libbpf-dev build-essential
   # 安装 Python 3 (用于端到端测试)
   sudo apt-get install -y python3 python3-pip python3-venv
   # 安装 Docker (可选)
   sudo apt-get install -y docker.io docker-buildx
   

2. 安装 Go 语言环境 (需 Go 1.24+)：

   # 下载并安装 Go (以 1.24.1 为例)
   wget https://go.dev/dl/go1.24.1.linux-amd64.tar.gz
   sudo rm -rf /usr/local/go
   sudo tar -C /usr/local -xzf go1.24.1.linux-amd64.tar.gz
   
   # 配置环境变量 (建议添加到 ~/.bashrc)
   export PATH=$PATH:/usr/local/go/bin
   

3. 克隆并编译：

   git clone https://github.com/alex-ilgayev/mcpspy.git
   cd mcpspy
   make all
   

方法三：使用 Docker

如果您希望在不污染宿主机的情况下运行：

# 拉取最新镜像
docker pull ghcr.io/alex-ilgayev/mcpspy:latest

# 运行容器 (需要 --privileged 权限)
docker run --rm -it --privileged ghcr.io/alex-ilgayev/mcpspy:latest

基本使用

安装完成后，即可开始监控 MCP 通信。

1. 启动监控 (交互模式)

默认情况下，MCPSpy 以交互式终端界面 (TUI) 启动，提供实时表格视图、消息详情查看和过滤功能：

sudo mcpspy

• 操作提示：按 Enter 查看详细消息，按 q 或 Ctrl+C 退出。

2. 静态控制台输出

如果您只需要简单的文本日志流，可以禁用 TUI：

sudo mcpspy --tui=false

3. 保存日志到文件

将监控到的 JSON-RPC 消息保存为 JSONL 格式以便后续分析：

sudo mcpspy -o output.jsonl

4. 启用提示词注入检测 (高级)

MCPSpy 支持实时检测提示词注入攻击。您需要提供 HuggingFace API Token：

# 启用安全检查并指定 Token
sudo mcpspy --security --hf-token=hf_xxxxx

• 当检测到潜在攻击时，工具会显示风险等级（低/中/高/严重）及告警详情。