wireshark-mcp

---

这是什么？

一个 MCP 服务，将 tshark（以及可选的 Wireshark 套件工具）封装为结构化分析接口。可与 Claude Desktop、Claude Code、Cursor、VS Code 及其他 18 种以上的 MCP 客户端配合使用。

You:    "Find all DNS queries going to suspicious domains in this capture."
Claude: [calls wireshark_extract_dns_queries → wireshark_detect_dns_tunnel]
        "Found repeated high-entropy DNS queries consistent with tunneling: ..."

4.0 新增内容

• 捕获文件索引。 使用可选的 [index] 附加组件，wireshark_index 会将捕获文件解析一次并写入本地 DuckDB 文件。之后，wireshark_aggregate 和 wireshark_extract_fields 调用会从中读取数据，结果与 tshark 相同：在 1 GB 文件上快 408 倍；在 10 GB 文件上，还能回答 tshark 路径无法处理的问题。此外，还支持只读 SQL、捕获文件集、首次出现时间线、捕获文件或时间窗口差异比较，以及 Parquet 导出。请参阅捕获文件索引。
• 统一的发现格式。 每个检测器都会返回 data.findings，其中包含稳定的 ID、证据锚点、用于重新核验的原生 tshark 命令，以及候选 ATT&CK 技术。
• 案例文件。 wireshark_case 会将捕获文件、记录的结果、发现和分析人员判定保存在 JSON 案例文件中，让长期调查在上下文重置后仍能继续。请参阅发现与案例。

从 3.x 升级无需更改配置。解析 wireshark_detect_beaconing、wireshark_detect_exfiltration、wireshark_detect_protocol_anomalies、wireshark_detect_arp_spoofing、wireshark_yara_scan 或 wireshark_quick_analysis 纯文本输出的脚本，应改为读取 JSON 封装。完整说明：4.0.0 更新日志。

---

安装

Claude Code / Codex 插件方式

前置条件：uv 和 Wireshark 命令行工具（tshark）。该插件包含本项目和两个技能；客户端通过 stdio 使用 uv 运行已锁定的 Python 项目。它不会安装 Wireshark 或捕获驱动程序。

在包含这些插件清单的检出目录中，选择你的客户端：

# Codex
codex plugin marketplace add .
codex plugin add wireshark-mcp@wireshark-mcp

# Claude Code
claude plugin marketplace add .
claude plugin install wireshark-mcp@wireshark-mcp

有关本地安装、旧版本刷新、环境设置以及发布后的 GitHub 入口，请参阅插件分发。请选择此方式或下方的传统注册方式，不要同时使用两者。

传统 Python 包安装方式

前提条件： Python 3.10+ 和 Wireshark，且 tshark 已添加到 PATH。

Wireshark MCP 使用稳定版 MCP Python SDK 2.x 系列（mcp>=2.1.1,<3）。

pip install wireshark-mcp
wireshark-mcp install   # choose from detected MCP clients

对于脚本／非交互式终端，请明确选择客户端。安装到当前项目之前，先预览：

wireshark-mcp install --client codex --scope project --dry-run
wireshark-mcp install --client codex --scope project

默认范围为 global。重复指定 --client，或明确使用 --client all。重启客户端以加载配置。有关更新、移除、备份和退出代码，请参阅安装指南。

可选扩展可在基础安装之上增加功能：index（用于大型捕获文件的 DuckDB 索引）、geoip（GeoIP 丰富数据）和 yara（YARA 扫描），也可安装 all：

pip install 'wireshark-mcp[index]'

容器镜像和插件安装方式不包含扩展。所有设置、扩展和限制均列于配置参考。

项目还附带 MCP 和完整的 TShark CLI 分析技能；请参阅技能发现与使用。

如果发现异常，请运行 wireshark-mcp doctor。手动设置或平台专属说明请参阅 docs/manual-configuration.md。

---

快速入门

将 .pcap 文件提供给 AI 客户端，然后试试：

Analyze capture.pcap using the Wireshark MCP tools.
Start with wireshark_open_file, then run wireshark_quick_analysis.
Use wireshark_aggregate for any capture-wide count or distribution.
Write findings to report.md.

对于大型捕获文件或多个相关文件，请先构建索引，并将调查记录保存在案件文件中：

Index big.pcapng with wireshark_index, then use wireshark_aggregate and
wireshark_index action="timeline" to find when 10.0.0.5 first appeared.
Open a case with wireshark_case, record every detector result you rely on,
and verify each conclusion with wireshark_get_packet_details.

---

工具

54 个工具，均由真实的 tshark 输出支持，并按类别整理：

类别	主要功能	数量
入口与工作流	wireshark_open_file、wireshark_quick_analysis、wireshark_case（持久化调查案件文件）	3
数据包分析	数据包列表、详情、字节、上下文、跟踪流、搜索、文件信息	8
数据提取	HTTP 请求、DNS 查询、任意字段、对象导出	4
统计	聚合／分组／去重／Top-k／时间桶、协议层级、端点、会话、I/O 图、专家信息、服务响应时间、流量图	8
安全与异常	凭据扫描、端口扫描、DNS 隧道、DoS、信标通信、数据外泄、协议异常、YARA	8
协议分析	wireshark_analyze_protocol（25 种协议，包括 BLE 配对、扫描器检测、带句柄标签的 GATT 时间线、连接生命周期）、TCP 健康状况、ARP 欺骗	3
解密与解析	TLS/WPA 解密、解密检查、解码为、协议首选项	5
取证与数据丰富	TLS 指纹、文件签名扫描、GeoIP	3
文件操作、捕获与套件	实时捕获、接口、合并、筛选并保存、editcap 修剪／拆分／去重／时间平移、帧提取、text2pcap、功能	11
捕获索引（可选的 [index] 扩展）	wireshark_index：通过一次 tshark 扫描写入本地 DuckDB 文件；wireshark_aggregate 和 wireshark_extract_fields 可复用该索引。只读 SQL、多捕获文件集、首次出现时间线、捕获文件／时间窗口差异和 Parquet 导出	1

一个工具涵盖 25 种协议，而不是 25 个工具各自涵盖一种：wireshark_analyze_protocol 接受 protocol 参数（tls_handshakes、mqtt、modbus、s7comm、zigbee、wifi、rtp、kerberos 等），并应用相应的字段和显示筛选器。字段名称正是关键所在——调用方不应被迫猜测 s7comm.param.item.dbnum；猜错会返回空结果，看起来就像捕获文件没有问题一样。

服务启动时只要求有 tshark。可选工具（capinfos、mergecap、editcap、dumpcap、text2pcap）会自动检测，并在可用时启用额外功能。

上下文成本

工具列表会随客户端发送的每个请求一起放在提示词前缀中，因此其大小是每个请求的固定成本。默认占用约 23 KB——其中约 9 KB 为参数架构、5 KB 为描述、3 KB 为读写标注——并且在重启后字节内容完全一致，因此客户端可以缓存此前缀，而不必在每个会话中重新读取。

如果客户端从不捕获实时流量或写入 pcap，--profile 可以减少占用：

配置文件	工具数	负载	移除内容
full（默认）	54	~23 KB	无
analysis	42	~18 KB	实时捕获、接口列表、所有由调用方指定写入文件的工具
core	34	~15 KB	上述内容，外加解密、分解覆盖项和底层视图

wireshark-mcp serve --profile core

运行时提示词和协议建议会遵循所选配置文件。静态指南可能会介绍仅适用于 full 的工作流，但在捕获发现过程中，服务绝不会推荐已排除的工具。

工具结果也有大小限制，因为结果会在会话剩余时间内保留在对话中。超过 8000 个字符的输出会保留首尾部分并截断中间内容，同时附上标记；可以通过工具的 offset / limit / display_filter 参数分页查看其余内容。使用以下选项提高或降低上限：

export WIRESHARK_MCP_MAX_RESULT_CHARS=16000

每个工具还会声明其执行读取还是写入操作，因此客户端可以自动批准 41 个只读分析工具，同时仍要求确认会创建文件的 12 个工具（实时捕获、合并、保存筛选结果、editcap、text2pcap、帧提取、对象导出、案例文件）。wireshark_index 标记为非破坏性：它只会写入服务自身的索引缓存。

从 3.0 起，在 WIRESHARK_MCP_ALLOWED_DIRS 指定现有目录之前，这些工具都会默认拒绝执行。除非在受信任的身份验证 TLS 代理后显式提供 --allow-insecure-http，否则远程 HTTP/SSE 绑定也仅限环回地址。请参阅 3.0 安全迁移指南。

---

文档

主题	链接
文档索引	docs/README.md
配置参考（额外选项、环境变量、限制）	docs/configuration.md
全捕获聚合	docs/aggregation.md
捕获索引（DuckDB）	docs/capture-index.md
发现项和案例文件	docs/findings-and-cases.md
安装、更新和卸载	docs/installation.md
平台设置（macOS/Linux/Windows）	docs/platform-validation.md
手动配置客户端	docs/manual-configuration.md
部署场景	docs/deployment-scenarios.md
3.0 安全迁移	docs/security-hardening-v3.md
提示词模板	docs/prompt-engineering.md
架构	docs/architecture.md
发布检查清单	docs/release-checklist.md
参与贡献	CONTRIBUTING.md
更新日志	CHANGELOG.md
功能路线图	ROADMAP.md
安全策略	SECURITY.md

---

开发

uv sync --group dev --extra index
uv run python -m pytest
uv run python -m ruff check src/ tests/

完整指南请参阅 CONTRIBUTING.md。

---