Skip to content
Back to search

Wireshark-MCP

Wireshark-MCP,Give your AI assistant a packet analyzer. Drop a .pcap file, ask questions in plain English — get answers backed by real tshark data.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bx33661--wireshark-mcp/badge.svg)](/listings/bx33661--wireshark-mcp)

HTML

<a href="/listings/bx33661--wireshark-mcp"><img src="/api/listings/bx33661--wireshark-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code / Codex plugin route

Prerequisites: `uv` and Wireshark CLI (`tshark`). The plugin includes this project and both skills; the client runs the locked Python project through uv over stdio. It does not install Wireshark or capture drivers.

From a checkout containing these plugin manifests, choose your client:

# 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

See [plugin distribution](docs/plugin-installation.md) for local installation, old-version refresh, environment settings and the GitHub entrypoint after publication. Choose this route or the traditional registration route below, not both.

Traditional Python package route

**Prerequisites:** Python 3.10+ and [Wireshark](https://www.wireshark.org/) with `tshark` on PATH.

Wireshark MCP 3.0 uses the stable MCP Python SDK 2.x line (`mcp>=2.1.1,<3`).

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

For scripts/non-interactive terminals, select clients explicitly. Preview before installing into the current project:

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

The default scope is `global`. Repeat `--client` or explicitly use `--client all`. Restart the client to load configuration. See the [installation guide](docs/installation.md) for updates, removal, backups and exit codes.

The project also ships MCP and full TShark CLI analysis skills; see [skill discovery and usage](docs/skills.md).

Run `wireshark-mcp doctor` if anything looks off. See [docs/manual-configuration.md](docs/manual-configuration.md) for manual setup or platform-specific notes.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "wireshark-mcp",
  3. "owner": {
  4. "name": "bx33661"
  5. },
  6. "plugins": [
  7. {
  8. "name": "wireshark-mcp",
  9. "source": "./",
  10. "description": "Wireshark MCP server and packet-analysis skills"
  11. }
  12. ],
  13. "description": "Wireshark packet-analysis MCP server and investigation skills"
  14. }
README.md · README · 228 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <!-- mcp-name: io.github.bx33661/wireshark-mcp -->
  3. <img src="Logo.png" width="150" alt="Wireshark MCP" style="margin-top: 20px; margin-bottom: 20px;">
  4. <h1>Wireshark MCP</h1>
  5. **Give your AI assistant a packet analyzer.**
  6. *Drop a `.pcap` file, ask questions in plain English — get answers backed by real `tshark` data.*
  7. <p style="margin-top: 15px;">
  8. <a href="https://github.com/bx33661/Wireshark-MCP/actions/workflows/ci.yml">
  9. <img src="https://img.shields.io/github/actions/workflow/status/bx33661/Wireshark-MCP/ci.yml?style=flat-square&logo=github&label=CI" alt="CI">
  10. </a>
  11. <a href="https://github.com/bx33661/Wireshark-MCP/releases/latest">
  12. <img src="https://img.shields.io/github/v/release/bx33661/Wireshark-MCP?style=flat-square&logo=github&color=24292f" alt="GitHub Release">
  13. </a>
  14. <a href="https://pypi.org/project/wireshark-mcp/">
  15. <img src="https://img.shields.io/pypi/v/wireshark-mcp?style=flat-square&logo=pypi&color=0066cc" alt="PyPI">
  16. </a>
  17. <a href="https://pypi.org/project/wireshark-mcp/">
  18. <img src="https://img.shields.io/pypi/pyversions/wireshark-mcp?style=flat-square&logo=python" alt="Python">
  19. </a>
  20. <a href="LICENSE">
  21. <img src="https://img.shields.io/badge/License-MIT-green.svg?style=flat-square" alt="MIT License">
  22. </a>
  23. <a href="https://github.com/reacher-z/Awesome-REA"><img src="https://raw.githubusercontent.com/reacher-z/Awesome-REA/main/assets/featured-by-awesome-rea-inline.svg" alt="Featured by Awesome REA" width="184" height="20"></a>
  24. </p>
  25. <p>
  26. <a href="README.md"><b>English</b></a> •
  27. <a href="README_zh.md"><b>中文</b></a> •
  28. <a href="docs/README.md"><b>Docs</b></a> •
  29. <a href="CHANGELOG.md"><b>Changelog</b></a> •
  30. <a href="ROADMAP.md"><b>Roadmap</b></a> •
  31. <a href="CONTRIBUTING.md"><b>Contributing</b></a>
  32. </p>
  33. </div>
  34. ---
  35. ## What is this?
  36. An [MCP server](https://modelcontextprotocol.io/introduction) that wraps `tshark` (and optional Wireshark suite tools) into a structured analysis interface. Works with Claude Desktop, Claude Code, Cursor, VS Code, and 18+ other MCP clients.
  37. ```
  38. You: "Find all DNS queries going to suspicious domains in this capture."
  39. Claude: [calls wireshark_extract_dns_queries → wireshark_detect_dns_tunnel]
  40. "Found repeated high-entropy DNS queries consistent with tunneling: ..."
  41. ```
  42. ### New in 4.0
  43. - **Capture index.** With the optional `[index]` extra, `wireshark_index` dissects a capture once into a local DuckDB file. Later `wireshark_aggregate` and `wireshark_extract_fields` calls read it with answers identical to tshark: 408× faster at 1 GB, and at 10 GB it answers questions the tshark path stops on. It also adds read-only SQL, capture sets, first-seen timelines, capture or window diffs and Parquet export. See [Capture index](docs/capture-index.md).
  44. - **One finding shape.** Every detector returns `data.findings` with a stable id, evidence anchors, a native `tshark` command to re-check it and candidate ATT&CK techniques.
  45. - **Case files.** `wireshark_case` keeps captures, recorded results, findings and analyst verdicts in a JSON case file, so a long investigation survives a context reset. See [Findings and cases](docs/findings-and-cases.md).
  46. Upgrading from 3.x needs no configuration change. Scripts that parsed the plain-text output of `wireshark_detect_beaconing`, `wireshark_detect_exfiltration`, `wireshark_detect_protocol_anomalies`, `wireshark_detect_arp_spoofing`, `wireshark_yara_scan` or `wireshark_quick_analysis` should read the JSON envelope instead. Full notes: [4.0.0 changelog](changelog/4.0.0.md).
  47. ---
  48. ## Install
  49. ### Claude Code / Codex plugin route
  50. Prerequisites: `uv` and Wireshark CLI (`tshark`). The plugin includes this project and both skills; the client runs the locked Python project through uv over stdio. It does not install Wireshark or capture drivers.
  51. From a checkout containing these plugin manifests, choose your client:
  52. ```sh
  53. # Codex
  54. codex plugin marketplace add .
  55. codex plugin add wireshark-mcp@wireshark-mcp
  56. # Claude Code
  57. claude plugin marketplace add .
  58. claude plugin install wireshark-mcp@wireshark-mcp
  59. ```
  60. See [plugin distribution](docs/plugin-installation.md) for local installation, old-version refresh, environment settings and the GitHub entrypoint after publication. Choose this route or the traditional registration route below, not both.
  61. ### Traditional Python package route
  62. **Prerequisites:** Python 3.10+ and [Wireshark](https://www.wireshark.org/) with `tshark` on PATH.
  63. Wireshark MCP runs on the stable MCP Python SDK 2.x line (`mcp>=2.1.1,<3`).
  64. ```sh
  65. pip install wireshark-mcp
  66. wireshark-mcp install # choose from detected MCP clients
  67. ```
  68. For scripts/non-interactive terminals, select clients explicitly. Preview before installing into the current project:
  69. ```sh
  70. wireshark-mcp install --client codex --scope project --dry-run
  71. wireshark-mcp install --client codex --scope project
  72. ```
  73. The default scope is `global`. Repeat `--client` or explicitly use `--client all`. Restart the client to load configuration. See the [installation guide](docs/installation.md) for updates, removal, backups and exit codes.
  74. Optional extras add features on top of the base install: `index` (DuckDB capture index for large captures), `geoip` (GeoIP enrichment) and `yara` (YARA scanning), or `all`:
  75. ```sh
  76. pip install 'wireshark-mcp[index]'
  77. ```
  78. The container image and the plugin route ship without extras. Every setting, extra and limit is listed in the [configuration reference](docs/configuration.md).
  79. The project also ships MCP and full TShark CLI analysis skills; see [skill discovery and usage](docs/skills.md).
  80. Run `wireshark-mcp doctor` if anything looks off. See [docs/manual-configuration.md](docs/manual-configuration.md) for manual setup or platform-specific notes.
  81. ---
  82. ## Quick Start
  83. Point your AI client at a `.pcap` file and try:
  84. ```
  85. Analyze capture.pcap using the Wireshark MCP tools.
  86. Start with wireshark_open_file, then run wireshark_quick_analysis.
  87. Use wireshark_aggregate for any capture-wide count or distribution.
  88. Write findings to report.md.
  89. ```
  90. For a large capture, or several related ones, build the index first and keep the investigation in a case file:
  91. ```
  92. Index big.pcapng with wireshark_index, then use wireshark_aggregate and
  93. wireshark_index action="timeline" to find when 10.0.0.5 first appeared.
  94. Open a case with wireshark_case, record every detector result you rely on,
  95. and verify each conclusion with wireshark_get_packet_details.
  96. ```
  97. ---
  98. ## Tools
  99. 54 tools, each backed by real `tshark` output — organized into categories:
  100. | Category | Highlights | Count |
  101. |----------|-----------|:-----:|
  102. | **Entry & Workflow** | `wireshark_open_file`, `wireshark_quick_analysis`, `wireshark_case` (persistent investigation case files) | 3 |
  103. | **Packet Analysis** | Packet list, details, bytes, context, stream follow, search, file info | 8 |
  104. | **Data Extraction** | HTTP requests, DNS queries, arbitrary fields, object export | 4 |
  105. | **Statistics** | Aggregate/group/distinct/top-k/time buckets, protocol hierarchy, endpoints, conversations, I/O graph, expert info, service response time, flow graph | 8 |
  106. | **Security & Anomaly** | Credential scan, port scan, DNS tunnel, DoS, beaconing, exfiltration, protocol anomalies, YARA | 8 |
  107. | **Protocol Analysis** | `wireshark_analyze_protocol` (25 protocols incl. BLE pairing, scanner detection, GATT timeline with handle labels, connection lifecycle), TCP health, ARP spoofing | 3 |
  108. | **Decrypt & Dissection** | TLS/WPA decrypt, decryption check, decode-as, protocol preferences | 5 |
  109. | **Forensics & Enrichment** | TLS fingerprints, file signature scan, GeoIP | 3 |
  110. | **File Ops, Capture & Suite** | Live capture, interfaces, merge, filter-save, editcap trim/split/dedup/time-shift, frame extract, text2pcap, capabilities | 11 |
  111. | **Capture Index** (optional `[index]` extra) | `wireshark_index`: one tshark pass into a local DuckDB file; `wireshark_aggregate` and `wireshark_extract_fields` reuse it. Read-only SQL, multi-capture sets, first-seen timelines, capture/window diffs and Parquet export | 1 |
  112. One tool covers 25 protocols rather than 25 tools covering one each: `wireshark_analyze_protocol` takes a `protocol` argument (`tls_handshakes`, `mqtt`, `modbus`, `s7comm`, `zigbee`, `wifi`, `rtp`, `kerberos`, …) and applies the right fields and display filter for it. The field names are the point — `s7comm.param.item.dbnum` is not something a caller should have to guess, and a wrong guess returns an empty result that reads like a clean capture.
  113. The server starts with only `tshark` required. Optional tools (`capinfos`, `mergecap`, `editcap`, `dumpcap`, `text2pcap`) are auto-detected and enable extra features when present.
  114. ### Context cost
  115. The tool list travels in the prompt prefix of every request your client sends, so its size is a fixed per-request cost. The default surface is ~23 KB — about 9 KB of parameter schema, 5 KB of descriptions, and 3 KB of read/write annotations — and it is byte-identical across restarts so clients can cache the prefix rather than re-reading it each session.
  116. If your client never captures live traffic or writes pcaps, `--profile` advertises less:
  117. | Profile | Tools | Payload | Drops |
  118. |---------|:-----:|:-------:|-------|
  119. | `full` (default) | 54 | ~23 KB | nothing |
  120. | `analysis` | 42 | ~18 KB | live capture, interface listing, all caller-directed file-writing tools |
  121. | `core` | 34 | ~15 KB | the above, plus decryption, dissection overrides, and low-level views |
  122. ```bash
  123. wireshark-mcp serve --profile core
  124. ```
  125. Runtime prompts and protocol recommendations respect the selected profile. Static guides may describe `full`-only workflows, but the server never recommends an excluded tool during capture discovery.
  126. Tool results are bounded too, since a result stays in the conversation for the rest of the session. Output over 8000 characters is truncated head-and-tail with a marker, and the tool's `offset` / `limit` / `display_filter` parameters are the way to page through the rest. Raise or lower the ceiling with:
  127. ```bash
  128. export WIRESHARK_MCP_MAX_RESULT_CHARS=16000
  129. ```
  130. Every tool also declares whether it reads or writes, so clients can auto-approve the 41 read-only analysis tools and still prompt for the 12 that create files (live capture, merge, filter-save, editcap, text2pcap, frame extract, object export, case files). `wireshark_index` is marked non-destructive: it writes only the server's own index cache.
  131. Since 3.0, those tools fail closed until `WIRESHARK_MCP_ALLOWED_DIRS` names existing directories. Remote HTTP/SSE binding also stays loopback-only unless `--allow-insecure-http` is explicitly supplied behind a trusted authenticated TLS proxy. See the [3.0 security migration guide](docs/security-hardening-v3.md).
  132. ---
  133. ## Documentation
  134. | Topic | Link |
  135. |-------|------|
  136. | Documentation index | [docs/README.md](docs/README.md) |
  137. | Configuration reference (extras, environment variables, limits) | [docs/configuration.md](docs/configuration.md) |
  138. | Capture-wide aggregation | [docs/aggregation.md](docs/aggregation.md) |
  139. | Capture index (DuckDB) | [docs/capture-index.md](docs/capture-index.md) |
  140. | Findings and case files | [docs/findings-and-cases.md](docs/findings-and-cases.md) |
  141. | Install, update and uninstall | [docs/installation.md](docs/installation.md) |
  142. | Platform setup (macOS/Linux/Windows) | [docs/platform-validation.md](docs/platform-validation.md) |
  143. | Manual client configuration | [docs/manual-configuration.md](docs/manual-configuration.md) |
  144. | Deployment scenarios | [docs/deployment-scenarios.md](docs/deployment-scenarios.md) |
  145. | 3.0 security migration | [docs/security-hardening-v3.md](docs/security-hardening-v3.md) |
  146. | Prompt templates | [docs/prompt-engineering.md](docs/prompt-engineering.md) |
  147. | Architecture | [docs/architecture.md](docs/architecture.md) |
  148. | Release checklist | [docs/release-checklist.md](docs/release-checklist.md) |
  149. | Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
  150. | Changelog | [CHANGELOG.md](CHANGELOG.md) |
  151. | Feature roadmap | [ROADMAP.md](ROADMAP.md) |
  152. | Security policy | [SECURITY.md](SECURITY.md) |
  153. ---
  154. ## Development
  155. ```sh
  156. uv sync --group dev --extra index
  157. uv run python -m pytest
  158. uv run python -m ruff check src/ tests/
  159. ```
  160. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
  161. ---
  162. <div align="center">
  163. <sub><a href="LICENSE">MIT License</a> · <a href="https://github.com/bx33661/Wireshark-MCP/issues">Report a Bug</a></sub>
  164. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.