# wireshark-mcp-win

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

[English](README.en.md)

## 功能

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](https://www.wireshark.org/)（含 tshark/dumpcap/capinfos/editcap/mergecap 与 Npcap 驱动）
- Python 3.10+（开发环境 3.13）

## 安装

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

## 启动

```bash
# 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`）

```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=...)` 翻页分析。

## 开发与自测

```bash
# 生成合成测试样本（含完整 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 完成