Wireshark MCP

基于 FastMCP 的 MCP 服务器，为 AI 代理和本地测试提供 Wireshark/tshark 捕获、分析、威胁检测和报告工具。

目录

• 先决条件

• 快速入门

• 运行服务器

• 使用工具（示例）

• 可用工具（摘要）

• 故障排除

• 贡献

先决条件

• Python: 3.8+ (推荐 3.11)

• Wireshark (用于 tshark CLI)。在 Windows 上，请安装 Wireshark + Npcap。

• 权限: 在 Windows 上，数据包捕获通常需要提升的权限。

确保已安装 tshark 或其在常用路径中可用（例如 C:\Program Files\Wireshark\tshark.exe）。该项目包含一个 TsharkWrapper，它会在 PATH 和常见的 Windows 安装位置中查找。

Related MCP server: wireshark-mcp

快速入门

克隆存储库并创建虚拟环境。

Windows (PowerShell):

git clone <your-repo-url>
cd Wireshark_MCP
python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Linux / macOS:

git clone <your-repo-url>
cd Wireshark_MCP
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

可选：将 config.example.json 复制到 config.json 并编辑任何特定于项目的设置。

运行服务器

有两种常见模式：

• stdio 传输 — 旨在与支持 MCP 的客户端（例如 Wireshark/IDE 集成）直接集成。这是运行主包时的默认设置。

• http 传输 — 通过 HTTP API 公开 MCP 服务器（适用于测试或外部客户端）。

推荐（Windows）：使用随附的运行程序，它会激活 venv 并启动服务器：

.\run_server.ps1

手动运行 (stdio)：

.\venv\Scripts\Activate.ps1
python -m wireshark_mcp.server

使用 HTTP 传输启动（示例脚本）。创建 run_network_server.py 并写入：

from wireshark_mcp import server

# Starts FastMCP with HTTP transport on 127.0.0.1:8765
server.main().run(transport="http", host="127.0.0.1", port=8765)

运行它：

python run_network_server.py

当使用 HTTP 传输启动时，您将看到类似以下的 Uvicorn 日志：

INFO:     Uvicorn running on http://127.0.0.1:8765 (Press CTRL+C to quit)

使用工具（示例）

对于开发和测试，我们建议直接调用工具模块（这些模块返回结构化的 Python 对象）。服务器的 MCP 装饰函数返回用于 MCP 传输的序列化字符串。

Python 示例（在激活的 venv 中）：

# List network interfaces (preferred for testing)
from wireshark_mcp.tools import capture
print(capture.list_network_interfaces())

# Analyze a PCAP file
from wireshark_mcp.tools import analysis
print(analysis.analyze_pcap("/path/to/capture.pcap"))

# Detect threats in a PCAP
from wireshark_mcp.tools import threat_detection
print(threat_detection.detect_threats("/path/to/capture.pcap"))

如果您想通过服务器层使用 MCP 工具（MCP 客户端将调用这些工具），服务器会公开同名工具。示例（注意：这些返回字符串）：

from wireshark_mcp import server
print(server.list_network_interfaces())  # returns serialized string

可用工具（摘要）

捕获

• list_network_interfaces — 列出可用的捕获设备

• capture_packets — 捕获实时数据包（接口、持续时间、packet_count、bpf_filter）

分析

• analyze_pcap — 全面的 pcap 分析

• extract_dns_queries — DNS 查询和可疑域名

• extract_ip_addresses — IP 提取和流量模式

• get_protocol_statistics — 协议分布

威胁检测

• detect_threats — IOC 提取和风险评分

• analyze_malicious_domains — 域名深度分析

• analyze_suspicious_ips — IP 信誉检查

• detect_attack_patterns — 签名/模式检测

故障排除

• analyze_connectivity_issue — 目标连接诊断

• analyze_vpn_behavior — VPN 与非 VPN 对比

• analyze_latency_and_retransmissions — 数据包丢失和重传

• analyze_web_performance — Web 应用流量分析

报告

• generate_analysis_report — 综合报告生成

• generate_security_report — 以安全为重点的报告

有关确切的工具签名和文档字符串，请参阅 wireshark_mcp/server.py。

故障排除

• 找不到 tshark：安装 Wireshark 并确保 tshark 在 PATH 中或存在于默认安装文件夹中。当 PATH 中不包含 tshark 时，随附的 TsharkWrapper 会查找常见的 Windows 位置。

• Windows 上的捕获权限错误：确保已安装 Npcap 并以管理员身份运行 PowerShell。

• 如果工具返回带有错误字符串的 failed，请直接在 wireshark_mcp.tools 中运行等效函数以检查异常。

日志：服务器使用标准日志记录；请检查您启动服务器时的控制台输出以获取详细信息。

贡献

• 在功能分支上进行更改，在适当的地方添加测试，并提交拉取请求。

• 保持 wireshark_mcp.tools 中的公共 API 稳定；装饰后的 server 函数仅用于 MCP 公开。

许可证

在发布到 GitHub 之前，请添加您首选的许可证文件（例如 LICENSE）。

如果您愿意，我还可以：

• 创建一个简短的 CONTRIBUTING.md，

• 在 scripts/ 文件夹下添加示例脚本（HTTP 运行程序、快速测试片段），或者

• 为您打开一个本地 Git 分支并提交这些更改。

安全与代码质量

该项目定期使用静态分析工具 (SonarQube) 进行扫描，以发现安全、可靠性和可维护性问题。下方的截图截取自最近一次扫描，并在此处作为利益相关者的支持证据。

注意：截图显示的是拍摄时的分析状态。权威来源是 SonarQube 项目页面 — 如果您公开这些工件，请包含该链接。

图表参考（将图像文件放在 docs/images/ 中）：

• docs/images/sonarqube_result.jpeg — 项目摘要 / 总体状态 (SonarQube)

• docs/images/snyk_result.jpeg — 依赖项/安全扫描摘要 (Snyk)

图 1 — SonarQube 项目摘要（扫描时通过 / 无未解决的安全或可靠性问题）。

图 2 — Snyk 扫描输出，说明了依赖项/安全检查和计数。

如何将图像添加到此存储库：

1. 在存储库根目录创建文件夹 docs/images/。

2. 将截图保存为 sonar_project.png 和 sonar_summary.png 到该文件夹中。

3. 将图像与 README 一起提交并推送到存储库：

git add docs/images/sonar_project.png docs/images/sonar_summary.png README.md
git commit -m "docs: add SonarQube screenshots to README"
git push origin <your-branch>

如果您愿意，可以在此处上传截图（或授予对 SonarQube 项目 URL 的访问权限），我将为您添加并提交它们。