mcpcap

mcpcap

一个用于分析 PCAP 文件的模块化 Python MCP（Model Context Protocol）服务。mcpcap 提供特定协议的分析工具，调用时可接受本地文件路径或远程 HTTP URL，因此服务保持无状态，并能与 MCP 客户端顺畅配合。

概述

mcpcap 采用模块化架构，用于分析 PCAP 文件中的不同网络协议。每个模块都提供专用分析工具，可使用任意 PCAP 文件独立调用，因此非常适合与 Claude Desktop 和其他 MCP 客户端集成。

主要功能

• 无状态 MCP 工具：每次分析调用都会提供自己的 PCAP 路径或 URL
• 模块化架构：包含 DNS、DHCP、ICMP、TCP、SIP 和 CapInfos 模块，并可轻松扩展以支持新协议
• 高级 TCP 分析：连接生命周期、流量模式、重传和流检查
• 支持本地和远程 PCAP：分析本地存储中的文件或 HTTP URL
• Scapy 集成：利用 scapy 全面的数据包解析能力
• 专用分析提示词：提供安全、网络和取证分析指引
• JSON 响应：采用针对大模型优化的结构化数据格式

安装

mcpcap 需要 Python 3.10 或更高版本。

使用 pip

pip install mcpcap

使用 uv

uv add mcpcap

使用 uvx（用于一次性使用）

uvx mcpcap

使用 Docker

从仓库根目录构建镜像：

docker build -t mcpcap .

通过 HTTP 运行，以供连接到网络端点的 MCP 客户端使用：

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -v "$(pwd)/examples:/pcaps:ro" \
  mcpcap --transport http --host 0.0.0.0 --port 8080 --allow-unauthenticated-http

通过 stdio 运行，以供能够直接启动 docker run 的客户端使用：

docker run --rm -i \
  -v "$(pwd)/examples:/pcaps:ro" \
  mcpcap

将本地抓包文件挂载到容器时，请在工具调用中使用容器路径：

analyze_dns_packets("/pcaps/dns.pcap")

远程 http:// 和 https:// PCAP URL 无需挂载卷即可使用，因为 mcpcap 会在调用时于容器内下载文件。

使用 Docker Compose

对于默认的 HTTP 工作流，启动随附的 Compose 服务：

docker compose up

此命令会拉取 ghcr.io/mcpcap/mcpcap:latest，仅在主机环回接口上发布 http://127.0.0.1:8080/mcp，并将 ./examples 挂载到容器中的 /pcaps。

analyze_dns_packets("/pcaps/dns.pcap")

要分析自己的抓包文件，请在 docker-compose.yml 中将卷从 ./examples:/pcaps:ro 更改为本地抓包文件目录。

要使用已检出的源代码进行本地开发，而不是使用 GHCR：

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

快速入门

1. 启动 MCP 服务

将 mcpcap 作为无状态 MCP 服务启动：

# Default stdio transport for Claude Desktop and similar clients
mcpcap

# Start with specific modules only
mcpcap --modules dns,tcp

# With packet analysis limits
mcpcap --max-packets 1000

# Start an HTTP transport server for remote MCP clients
mcpcap --transport http --host 127.0.0.1 --port 8080

2. 连接 MCP 客户端

对 Claude Desktop 等本地 MCP 客户端使用 stdio 传输：

{
  "mcpServers": {
    "mcpcap": {
      "command": "mcpcap",
      "args": []
    }
  }
}

当 MCP 客户端需要网络端点时，使用 HTTP 传输：

mcpcap --transport http --host 127.0.0.1 --port 8080

将支持 HTTP 的 MCP 客户端指向：

http://127.0.0.1:8080/mcp

Docker 用户可以通过以下命令发布同一端点：

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -v "/path/to/captures:/pcaps:ro" \
  mcpcap --transport http --host 0.0.0.0 --port 8080 --allow-unauthenticated-http

也可以使用 Compose：

docker compose up

在非环回接口上绑定 HTTP 时，需要设置 MCPCAP_AUTH_TOKEN 环境密钥。请通过密钥管理器设置高强度随机密钥，或在输入时避免将其记录到 Shell 历史记录中：

read -rs -p "HTTP bearer token: " MCPCAP_AUTH_TOKEN
export MCPCAP_AUTH_TOKEN
mcpcap --transport http --host 0.0.0.0 --port 8080

客户端每次请求都必须发送 Authorization: Bearer <secret>。对远程客户端，请使用 TLS 反向代理和 HTTPS URL。配置令牌也会保护环回端点；stdio 不受影响。Docker 示例使用 --allow-unauthenticated-http 在容器内绑定，同时仅向主机环回接口发布。请保留此环回映射，并使用可信的本地 Docker 网络；同一网络上的其他容器可以访问该服务。设置 MCPCAP_AUTH_TOKEN 后，Compose 会转发该变量，因此你也可以保护本地容器端点。详情请参阅 HTTP 集成指南。

3. 分析 PCAP 文件

调用工具时，提供文件路径或 URL，即可使用任意 PCAP 文件运行分析工具：

DNS 分析：

analyze_dns_packets("/path/to/dns.pcap")
analyze_dns_packets("https://example.com/remote.pcap")

DHCP 分析：

analyze_dhcp_packets("/path/to/dhcp.pcap")
analyze_dhcp_packets("https://example.com/dhcp-capture.pcap")

ICMP 分析：

analyze_icmp_packets("/path/to/icmp.pcap")
analyze_icmp_packets("https://example.com/ping-capture.pcap")

TCP 连接分析：

analyze_tcp_connections("/path/to/capture.pcap")
analyze_tcp_connections("/path/to/capture.pcap", server_ip="192.168.1.1", server_port=80)

TCP 模式分析：

analyze_tcp_anomalies("/path/to/capture.pcap", server_ip="10.0.0.1")

TCP 重传分析：

analyze_tcp_retransmissions("/path/to/capture.pcap")

流量流分析：

analyze_traffic_flow("/path/to/capture.pcap", server_ip="192.168.1.100")

SIP 分析：

analyze_sip_packets("/path/to/voip-signaling.pcap")
analyze_sip_packets("https://example.com/sip-call-flow.pcap")

CapInfos 分析：

analyze_capinfos("/path/to/any.pcap")
analyze_capinfos("https://example.com/capture.pcap")

如果你使用 Docker 并配置了绑定挂载，请传入容器内的路径，而不是主机路径：

analyze_capinfos("/pcaps/dns.pcap")

可用工具

DNS 分析工具

• analyze_dns_packets(pcap_file)：完整的 DNS 流量分析
  • 提取 DNS 查询和响应
  • 识别查询的域名和子域名
  • 分析查询类型（A、AAAA、MX、CNAME 等）
  • 跟踪查询频率和模式
  • 检测潜在的安全问题

DHCP 分析工具

• analyze_dhcp_packets(pcap_file)：完整的 DHCP 流量分析
  • 跟踪 DHCP 事务（DISCOVER、OFFER、REQUEST、ACK）
  • 识别 DHCP 客户端和服务
  • 监控 IP 地址分配和租约信息
  • 分析 DHCP 选项和配置
  • 检测 DHCP 异常和安全问题

ICMP 分析工具

• analyze_icmp_packets(pcap_file)：完整的 ICMP 流量分析
  • 分析 Ping 请求和响应及其响应时间
  • 识别网络连接和可达性问题
  • 跟踪 TTL 值和路由路径（traceroute 数据）
  • 检测 ICMP 错误消息（不可达、超时）
  • 监控潜在的基于 ICMP 的攻击或侦察活动

TCP 分析工具

• analyze_tcp_connections(pcap_file, server_ip=None, server_port=None, detailed=False)：TCP 连接状态分析

  • 跟踪 TCP 三次握手（SYN、SYN-ACK、ACK）
  • 分析连接生命周期和终止过程（FIN、RST）
  • 识别成功和失败的连接
  • 按服务器 IP 和／或端口筛选
  • 检测连接问题和异常关闭

• analyze_tcp_anomalies(pcap_file, server_ip=None, server_port=None)：TCP 流量观测分析

  • 汇总握手、标志、重置和重传情况
  • 显示方向性 RST 和重传模式
  • 报告连接生命周期指标
  • 返回供进一步调查的客观流量模式

• analyze_tcp_retransmissions(pcap_file, server_ip=None, threshold=0.02)：TCP 重传分析

  • 衡量总体及各连接的重传率
  • 识别存在质量问题的连接
  • 与可配置阈值进行比较
  • 检测网络拥塞和丢包

• analyze_traffic_flow(pcap_file, server_ip, server_port=None)：双向流量分析

  • 分析客户端到服务器与服务器到客户端的流量
  • 识别流量不对称
  • 确定 RST 数据包的来源
  • 解读连接模式和行为

SIP 分析工具

• analyze_sip_packets(pcap_file)：SIP 信令分析
  • 解析 UDP 和 TCP 传输上的 SIP 请求和响应
  • 提取呼叫标识符、CSeq 值、端点和关键的信令标头
  • 汇总请求方法和响应代码类别
  • 显示用户代理、信令服务器和传输方式
  • 支持 VoIP 故障排查、安全审查和取证重建

CapInfos 分析工具

• analyze_capinfos(pcap_file)：PCAP 文件元数据和统计信息
  • 文件信息（大小、名称、链路层封装）
  • 数据包统计信息（数量、数据大小、平均数据包大小）
  • 时间分析（持续时间、时间戳、数据包速率）
  • 数据吞吐量指标（字节／秒、比特／秒）
  • 类似于 Wireshark 的 capinfos(1) 实用工具

分析提示词

mcpcap 提供专用的分析提示词，以指导大模型分析：

DNS 提示词

• security_analysis - 专注于威胁检测、DGA 域名和 DNS 隧道
• network_troubleshooting - 识别 DNS 性能和配置问题
• forensic_investigation - 重建时间线并收集证据

DHCP 提示词

• dhcp_network_analysis - 网络管理和 IP 管理
• dhcp_security_analysis - 安全威胁和恶意 DHCP 检测
• dhcp_forensic_investigation - DHCP 事务的取证分析

ICMP 提示词

• icmp_network_diagnostics - 网络连通性和路径分析
• icmp_security_analysis - 基于 ICMP 的攻击和侦察行为检测
• icmp_forensic_investigation - 重建时间线并绘制网络拓扑

TCP 提示词

• tcp_connection_troubleshooting - 连接问题、握手分析和连接终止模式
• tcp_security_analysis - 攻击检测、防火墙分析和异常识别

SIP 提示词

• sip_security_analysis - 注册滥用、电话盗用和信令暴露审查
• sip_troubleshooting_analysis - 呼叫建立进度、路由不匹配和响应代码故障
• sip_forensic_investigation - 按 Call-ID、CSeq、端点和传输方式重建时间线

配置选项

模块选择

# Load specific modules
mcpcap --modules dns              # DNS analysis only
mcpcap --modules tcp              # TCP analysis only
mcpcap --modules dhcp             # DHCP analysis only
mcpcap --modules icmp             # ICMP analysis only
mcpcap --modules sip              # SIP analysis only
mcpcap --modules dns,tcp          # DNS and TCP analysis
mcpcap --modules dns,dhcp,icmp,tcp,sip,capinfos    # All modules (default)

分析限制

# Limit packet analysis for large files
mcpcap --max-packets 1000

传输选项

# Default stdio transport
mcpcap

# HTTP transport for network-accessible MCP clients
mcpcap --transport http

# HTTP transport on a custom interface and port (requires MCPCAP_AUTH_TOKEN)
mcpcap --transport http --host 0.0.0.0 --port 9000

完整配置示例

mcpcap --modules dns,dhcp,icmp,tcp,sip,capinfos --max-packets 500

CLI 参考

mcpcap [--modules MODULES] [--max-packets N] [--transport {stdio,http}] [--host HOST] [--port PORT] [--allow-unauthenticated-http]

选项：

• --modules MODULES：要加载的模块，以逗号分隔（默认值：dns,dhcp,icmp,tcp,sip,capinfos）
  • 可用模块：dns、dhcp、icmp、tcp、sip、capinfos
• --max-packets N：每个文件要分析的最大数据包数（默认值：无限制）
• --transport {stdio,http}：要公开的 MCP 传输方式（默认值：stdio）
• --host HOST：HTTP 传输要绑定的主机（默认值：127.0.0.1）
• --port PORT：HTTP 传输要绑定的端口（默认值：8080）
• --allow-unauthenticated-http：仅当部署环境隔离时（例如使用回环地址发布端口的 Docker），允许绑定非回环地址且不提供令牌

示例：

# Start with all modules
mcpcap

# DNS and TCP analysis only
mcpcap --modules dns,tcp

# TCP analysis for troubleshooting connections
mcpcap --modules tcp

# With packet limits for large files
mcpcap --max-packets 1000

# Expose mcpcap over HTTP
mcpcap --transport http --host 127.0.0.1 --port 8080

示例

examples/ 目录中包含示例 PCAP 文件：

• dns.pcap - 用于测试 DNS 分析的 DNS 流量
• dhcp.pcap - DHCP 四次握手捕获文件

目前，examples/ 中没有附带 ICMP 示例捕获文件。

与 MCP Inspector 配合使用

npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector mcpcap

然后测试这些工具：

// In the MCP Inspector web interface
analyze_dns_packets("./examples/dns.pcap")
analyze_dhcp_packets("./examples/dhcp.pcap")
analyze_capinfos("./examples/dns.pcap")
analyze_tcp_connections("/absolute/path/to/capture.pcap")
analyze_sip_packets("/absolute/path/to/voip-signaling.pcap")

架构

mcpcap 的模块化设计支持轻松扩展：

核心组件

1. BaseModule：通用文件处理、验证和远程下载
2. 协议模块：DNS、DHCP、ICMP、TCP、SIP 和 CapInfos 实现
3. MCP 接口：工具注册和提示词管理
4. FastMCP 框架：MCP 服务实现

工具流程

MCP Client Request → analyze_*_packets(pcap_file)
                  → BaseModule.analyze_packets()
                  → Module._analyze_protocol_file()
                  → Structured JSON Response

添加新模块

通过以下步骤创建新的协议模块：

1. 继承 BaseModule
2. 实现 _analyze_protocol_file(pcap_file)
3. 向 MCP 服务注册分析工具
4. 添加专用分析提示词

未来可能会添加以下模块：

• HTTP/HTTPS 流量分析
• UDP 连接分析
• BGP 路由分析
• SSL/TLS 证书分析
• 网络取证工具
• 端口扫描检测

远程文件支持

两种分析工具都支持通过 HTTP/HTTPS URL 使用远程 PCAP 文件：

# Examples of remote analysis
analyze_dns_packets("https://raw.githubusercontent.com/mcpcap/mcpcap/main/examples/dns.pcap")
analyze_dhcp_packets("https://example.com/network-capture.pcap")
analyze_icmp_packets("https://example.com/ping-test.pcap")
analyze_capinfos("https://example.com/network-metadata.pcap")
analyze_tcp_connections("https://example.com/tcp-session.pcap")
analyze_sip_packets("https://example.com/sip-signaling.pcap")

功能：

• 自动下载到临时文件并在完成后清理
• 支持 .pcap、.pcapng 和 .cap 文件
• 支持 HTTP/HTTPS 协议

安全注意事项

分析 PCAP 文件时：

• 文件可能包含敏感的网络信息
• 可能时通过 HTTPS 执行远程下载
• 自动清理临时文件
• 请考虑远程文件的来源和可信度

贡献

欢迎贡献！可参与的方向：

• 新增协议模块：添加对 HTTP、BGP、TLS、RTP 等协议的支持
• 增强分析能力：改进现有的 DNS/DHCP 分析
• 安全功能：添加更多威胁检测能力
• 性能优化：优化对大型 PCAP 文件的分析

许可证

MIT

要求

• Python 3.10+
• scapy（用于数据包解析和分析）
• requests（用于远程文件访问）
• fastmcp（MCP 服务框架）

文档

• GitHub：github.com/mcpcap/mcpcap
• 文档：docs.mcpcap.ai
• 网站：mcpcap.ai

支持

如有疑问、问题或功能请求，请在 GitHub 上提交 issue。