Wireshark Win

基于 Model Context Protocol (MCP) 官方 Python SDK v2 的 Wireshark MCP 服务器（Windows 平台）。将 Wireshark 核心工作流暴露给 AI Agent：实时抓包、离线 pcap 分析、显示过滤器、统计、TCP/UDP 流重组、包导出与 Wireshark GUI 可视化展示。

English

功能

16 个 MCP 工具，底层封装 tshark / dumpcap / capinfos / editcap / mergecap：

工具	功能
list_interfaces	列出可抓包网卡
capture_packets	实时抓包（限时/限量/BPF 过滤器），存 pcapng
read_packets	读 pcap：显示过滤、字段提取、text/fields/json/hex 输出、翻页、强制解码、TLS 密钥解密
list_protocol_fields	查询协议字段表（进程内缓存）
validate_filter	校验显示过滤器语法
list_streams	列出 TCP/UDP 流，含端点、包数与字节数摘要
follow_stream	流重组（ascii/hex，支持显示过滤器限定范围）
get_statistics	统计：io / conv / endpoints / phs / http / http_req / expert / hosts / ip_hosts / dns / sip
file_info	pcap 文件元信息（capinfos）
merge_pcaps	多文件合并（mergecap）
edit_pcap	编辑：时间截取 / 分块 / 截断 / 去重（editcap）
decode_as	强制协议解码（tshark -d）
open_in_wireshark	在 Wireshark GUI 中打开 pcap（预置过滤器/跳转包号）
live_display_capture	启动 Wireshark GUI 实时抓包展示
export_packets	导出：pcapng/pcap/csv/json/pdml/psml/ek/text
export_objects	导出协议对象（http/smb/tftp/icmp/imf 嵌入式文件）

资源：wireshark://version、wireshark://interfaces、wireshark://file/{path}

提示模板：analyze_general / analyze_http / analyze_tls / analyze_dns / analyze_tcp

设计要点：

• 上下文安全：返回结果自动截断（默认 200 KB），大导出落盘只回传摘要与路径
• 路径白名单：写入类操作（抓包/导出/合并/编辑）限定在工作目录内；读取支持任意路径
• 性能优化：无过滤器单趟快速路径、翻页范围式过滤、过滤器校验缓存、字段表进程内缓存

环境要求

• Windows 10/11（本机已验证 Windows 11）
• 已安装 Wireshark（含 tshark/dumpcap/capinfos/editcap/mergecap 与 Npcap 驱动）
• Python 3.10+（开发环境 3.13）

安装

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt

启动

# stdio（默认，供 MCP 客户端拉起，如 opencode）
.venv\Scripts\python server.py

# Streamable HTTP 服务
.venv\Scripts\python server.py --transport streamable-http --host 127.0.0.1 --port 8000
# 客户端连接 http://127.0.0.1:8000/mcp

# SSE（旧版 HTTP 传输，兼容老客户端）
.venv\Scripts\python server.py --transport sse --port 8000

常用参数（--help 查看全部）：

参数	说明	默认值
--tshark-path	Wireshark 安装目录（缺省自动发现：注册表/PATH/常见路径）	自动
--working-dir	抓包输出目录	./captures
--output-dir	导出文件目录	./captures/exports
--max-output-bytes	单次返回给模型的结果上限，防上下文爆炸	200000
--verbose	调试日志	关

MCP 客户端配置

opencode（opencode.json）

{
  "mcp": {
    "wireshark-mcp-win": {
      "type": "local",
      "command": [
        "D:\\path\\to\\wireshark-mcp-win\\.venv\\Scripts\\python.exe",
        "D:\\path\\to\\wireshark-mcp-win\\server.py"
      ],
      "enabled": true
    }
  }
}

注意事项

• 抓包权限：实时抓包（capture_packets / live_display_capture）依赖 Npcap 驱动，非提权进程能否抓包取决于 Npcap 安装时的 ACL 设置（默认仅限管理员）。抓包报权限错误时，请以管理员身份运行本服务。
• TLS 解密：read_packets(keylog_file="...") 传入 SSLKEYLOGFILE 即可解密 HTTPS 流量。
• 大文件处理：先用 edit_pcap（去重/分块/时间截取）预处理，或用 read_packets(limit=..., offset=...) 翻页分析。

开发与自测

# 生成合成测试样本（含完整 TCP/HTTP 流 + DNS + ARP）
.venv\Scripts\python scripts\make_test_pcap.py -o captures\sample_http.pcapng

# 全量功能自测（SDK in-memory 客户端，31 项断言）
.venv\Scripts\python scripts\test_server.py

# GUI 实测（会弹出 Wireshark 窗口）
.venv\Scripts\python scripts\test_gui.py

目录结构

wireshark-mcp-win/
├── server.py            # 入口：MCPServer 装配 + argparse + 多传输 run()
├── requirements.txt
├── ws_mcp/
│   ├── tshark.py        # CLI 封装：路径自动发现 / 子进程 / 编码 / 超时 / GUI 分离启动
│   ├── tools.py         # 16 个 MCP 工具
│   ├── resources.py     # 资源
│   ├── prompts.py       # 提示模板
│   └── formatter.py     # 输出清洗与截断
├── scripts/             # 测试与样本生成脚本
└── captures/            # 抓包与导出文件（默认输出目录）

---

*该项目全程由 OpenCode + DeepSeek-V4-Pro-0813 完成