Wireshark MCP

FastMCP-based MCP server exposing Wireshark/tshark capture, analysis, threat-detection and reporting tools for AI agents and local testing.

---

Table of contents

• Prerequisites
• Quickstart
• Running the server
• Using tools (examples)
• Available tools (summary)
• Troubleshooting
• Contributing

---

Prerequisites

• Python: 3.8+ (3.11 recommended)
• Wireshark (for tshark CLI). On Windows install Wireshark + Npcap.
• Permissions: Packet capture typically requires elevated privileges on Windows.

Make sure tshark is installed or available in a common path (e.g. C:\Program Files\Wireshark\tshark.exe). The project includes a TsharkWrapper that looks in PATH and common Windows locations.

---

Quickstart

Clone the repository and create a virtual environment.

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

Optional: copy config.example.json to config.json and edit any project-specific settings.

---

Running the server

There are two common modes:

• stdio transport — intended for direct integration with MCP-capable clients (e.g., Wireshark/IDE integrations). This is the default when running the main package.
• http transport — exposes the MCP server over an HTTP API (useful for testing or external clients).

Recommended (Windows): use the included runner which activates the venv and starts the server:

.\run_server.ps1

Manual run (stdio):

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

Start with HTTP transport (example script). Create run_network_server.py with:

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)

Run it:

python run_network_server.py

When started with HTTP transport, you will see Uvicorn logs like:

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

---

Using tools (examples)

For development and testing we recommend calling the tool modules directly (these return structured Python objects). The server's MCP-decorated functions return serialized strings for MCP transport.

Python examples (inside activated 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"))

If you want to exercise the MCP tools via the server layer (MCP clients will call these), the server exposes the same-named tools. Example (note: these return strings):

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

---

Available tools (summary)

Capture

• list_network_interfaces — list available capture devices
• capture_packets — capture live packets (interface, duration, packet_count, bpf_filter)

Analysis

• analyze_pcap — full pcap analysis
• extract_dns_queries — DNS queries and suspicious domains
• extract_ip_addresses — IP extraction and traffic patterns
• get_protocol_statistics — protocol distribution

Threat Detection

• detect_threats — IOC extraction and risk scoring
• analyze_malicious_domains — domain deep-dive
• analyze_suspicious_ips — IP reputation checks
• detect_attack_patterns — signature/pattern detection

Troubleshooting

• analyze_connectivity_issue — target connectivity diagnostics
• analyze_vpn_behavior — VPN vs non-VPN comparison
• analyze_latency_and_retransmissions — packet loss and retransmissions
• analyze_web_performance — web application traffic analysis

Reporting

• generate_analysis_report — comprehensive report generation
• generate_security_report — security-focused report

See wireshark_mcp/server.py for exact tool signatures and docstrings.

---

Troubleshooting

• tshark not found: install Wireshark and ensure tshark is in PATH or present in the default install folder. The included TsharkWrapper looks for common Windows locations when PATH does not contain tshark.
• Permission errors capturing on Windows: ensure Npcap is installed and run PowerShell as Administrator.
• If a tool returns failed with an error string, run the equivalent function in wireshark_mcp.tools directly to inspect exceptions.

Logs: The server uses standard logging; check the console output where you started the server for details.

---

Contributing

• Make changes on a feature branch, add tests where appropriate, and open a pull request.
• Keep public APIs in wireshark_mcp.tools stable; the decorated server functions are for MCP exposure.

---

License

Add your preferred license file (e.g., LICENSE) before publishing to GitHub.

---

If you'd like, I can also:

• create a short CONTRIBUTING.md,
• add example scripts under a scripts/ folder (HTTP runner, quick-test snippets), or
• open a local Git branch and commit these changes for you.

---

Security & Code Quality

The project is scanned regularly with a static analysis tool (SonarQube) to surface security, reliability and maintainability issues. The screenshots below were captured from the most recent scan and are included here as supporting evidence for stakeholders.

Note: screenshots show the analysis state at the time they were taken. The authoritative source is the SonarQube project page — include that link if you publish these artifacts publicly.

Figure references (place the image files in docs/images/):

• docs/images/sonarqube_result.jpeg — project summary / overall status (SonarQube)
• docs/images/snyk_result.jpeg — dependency/security scan summary (Snyk)

Figure 1 — SonarQube project summary (Passed / no open security or reliability issues at scan time).

Figure 2 — Snyk scan output illustrating dependency/security checks and counts.

How to add the images to this repository:

1. Create the folder docs/images/ at the repository root.
2. Save the screenshots as sonar_project.png and sonar_summary.png into that folder.
3. Commit and push the images alongside the 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>

If you want, upload the screenshots here (or grant access to the SonarQube project URL) and I will add and commit them for you.