Skip to main content
Glama

English | 简体中文

wiresharkmcp

wiresharkmcp is a standalone MCP server that exposes Wireshark CLI tools to AI agents through MCP tools, resources, and prompts.

Usage Video

A short walkthrough of the repository setup and usage:

Related MCP server: Wireshark MCP

5-Minute Setup

1. Install Wireshark CLI

macOS:

  1. Install the official Wireshark .dmg.

  2. Move Wireshark.app to /Applications.

  3. Install ChmodBPF from the same .dmg.

Ubuntu/Debian:

sudo apt update
sudo apt install wireshark-common tshark

If you use another distro, need dftest, or want a source build, use the advanced guide in docs/advanced-install.md.

2. Install this repository

uv sync

3. Generate local config

Run the first-run helper:

uv run python scripts/doctor.py

It prints:

  • your current platform and detected Wireshark binaries

  • a suggested .env with absolute binary paths and a home-directory WIRESHARK_MCP_ALLOWED_ROOTS

  • a suggested stdio mcpServers JSON block

If you want it to create .env for you:

uv run python scripts/doctor.py --write-env

Status meanings:

  • usable: all core Wireshark binaries and dftest were found

  • usable but degraded: core binaries were found, but dftest is missing

  • not ready: one or more core binaries are still missing

Minimal .env shape:

WIRESHARK_MCP_ALLOWED_ROOTS=["/absolute/path/to/wireshark-mcp"]
WIRESHARK_MCP_TRANSPORT=stdio

doctor.py also fills any detected WIRESHARK_MCP_*_PATH entries with absolute paths so GUI clients do not depend on your shell PATH.

4. Paste the MCP config into your client and validate

Copy the Suggested MCP config block printed by doctor.py, or start from examples/mcp.json. The recommended command is:

{
  "mcpServers": {
    "wireshark-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/wiresharkmcp-public",
        "wireshark-mcp"
      ],
      "env": {
        "WIRESHARK_MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Then connect your MCP client and call ws_runtime_info. That one tool is the only required first-run validation step. It tells you:

  • which Wireshark binaries were found

  • which features are currently available

  • which filesystem roots the server can access

What the First-Run Helper Optimizes

  • It prefers explicit absolute binary paths over PATH, which is more reliable for desktop and GUI MCP clients.

  • On macOS it checks /Applications/Wireshark.app/Contents/MacOS first.

  • On Linux it checks PATH and common locations such as /usr/bin.

  • It refuses to overwrite an existing .env; if you already have one, it tells you to merge changes manually.

Advanced Docs

Security

  • The server only reads and writes files inside WIRESHARK_MCP_ALLOWED_ROOTS.

  • Do not commit .env, capture files, or generated logs from real environments.

License

MIT. See LICENSE.

Available Tools

38 tools
analysis_catalogA
Read-onlyIdempotent

Get the capability catalog of an analysis session: available taps, follow protocols, statistics, columns, and encapsulation types. Use this to discover what analysis operations are available.

Inputs: analysis_session_id (required). Returns: result

analysis_closeA
DestructiveIdempotent

Close an analysis session and release resources.

Inputs: analysis_session_id (required). Returns: result

analysis_download_artifactB
Idempotent

Download an exported object, RTP stream audio, or TLS key log from sharkd. Tokens come from analysis_get_statistics (export_objects, rtp_streams) or fixed tokens like 'ssl-secrets'.

Inputs: token (required), analysis_session_id (required), output_mode. Returns: result

analysis_follow_streamA
Idempotent

Reassemble and follow a protocol stream (TCP, UDP, TLS, HTTP, etc.). Use analysis_get_frame's follow_filters to get the protocol and filter values.

Inputs: filter (required), protocol (required), analysis_session_id (required), sub_stream, +1 more. Returns: result

analysis_get_frameB
Idempotent

Get the complete protocol dissection tree for a single frame. Returns protocol layers, field values, and optionally raw bytes.

Inputs: frame_number (required), analysis_session_id (required), ref_frame, bytes_mode, +4 more. Returns: result

analysis_get_statisticsB
Read-onlyIdempotent

Execute a sharkd tap for statistical analysis. Returns table, tree, or graph results depending on the tap type. Use analysis_catalog to discover available taps. Friendly selector shorthands such as 'conv,tcp' are accepted.

Inputs: analysis_session_id (required), kind, name, limit, +4 more. Returns: result

analysis_intervalsA
Read-onlyIdempotent

Get frame count and byte statistics per time interval. Useful for traffic pattern analysis.

Inputs: analysis_session_id (required), interval_ms, display_filter. Returns: result

analysis_iographB
Read-onlyIdempotent

Generate I/O graph time-series data. Specify up to 10 graph definitions with metrics and optional filters.

Inputs: graphs (required), analysis_session_id (required), interval, display_filter, +1 more. Returns: result

analysis_list_framesB
Read-onlyIdempotent

List frame summaries with optional display filter and pagination. Returns frame numbers, column values, and metadata flags.

Inputs: analysis_session_id (required), refs, skip, limit, +2 more. Returns: result

analysis_list_http_hostsA
Read-onlyIdempotent

List HTTP hosts grouped by request host with example methods and URIs.

Inputs: analysis_session_id (required), limit, max_packets, display_filter. Returns: result

analysis_list_sessionsA
Read-onlyIdempotent

List all analysis sessions, optionally filtered by status (ready, closed, failed).

Inputs: status. Returns: result

analysis_list_tcp_conversationsA
Read-onlyIdempotent

List TCP conversations without requiring manual sharkd tap syntax.

Inputs: analysis_session_id (required), limit, display_filter. Returns: result

analysis_list_tls_sniB
Read-onlyIdempotent

List TLS Server Name Indication values grouped by hostname.

Inputs: analysis_session_id (required), limit, max_packets, display_filter. Returns: result

analysis_openA

Open a capture file for analysis using sharkd. Either provide file_path directly or capture_session_id to select from capture output. Returns session ID and file summary.

Inputs: file_name, file_path, max_bytes, max_packets, +2 more. Returns: result

analysis_statusA
Read-onlyIdempotent

Get the current status of an analysis session including frame count and duration.

Inputs: analysis_session_id (required). Returns: result

analysis_summaryA
Read-onlyIdempotent

Get a comprehensive summary of the loaded capture file including frame count, duration, protocols, and time range.

Inputs: analysis_session_id (required). Returns: result

capture_get_interface_capabilitiesA
Read-onlyIdempotent

Get detailed capabilities of a specific network interface, including supported link types and timestamp types.

Inputs: interface (required). Returns: result

capture_list_filesA
Read-onlyIdempotent

List files produced by a capture session. In ring buffer mode, multiple files may exist.

Inputs: capture_session_id (required). Returns: result

capture_list_interfacesA
Read-onlyIdempotent

List available network interfaces for packet capture. Returns interface names, display names, and addresses.

Inputs: no named parameters. Returns: result

capture_list_sessionsB
Read-onlyIdempotent

List all capture sessions, optionally filtered by status.

Inputs: status. Returns: result

capture_read_logB
Read-onlyIdempotent

Read the capture session log (dumpcap stderr output).

Inputs: capture_session_id (required), tail. Returns: result

capture_startA

Start live packet capture on a network interface. Requires root or cap_net_raw capability. Returns a session ID for tracking.

Inputs: interface (required), autostop, output_dir, promiscuous, +7 more. Returns: result

capture_statusA
Read-onlyIdempotent

Get the current status of a capture session, including packet counts and file information.

Inputs: capture_session_id (required). Returns: result

capture_stopA
DestructiveIdempotent

Stop a running packet capture. Idempotent - safe to call multiple times.

Inputs: capture_session_id (required). Returns: result

field_getA
Read-onlyIdempotent

Get detailed information about a specific protocol field by its abbreviation (e.g., 'ip.src', 'tcp.port'). Use the 'id' value from field_list results. Requires an active analysis session.

Inputs: field_id (required), analysis_session_id (required). Returns: result

field_listA
Read-onlyIdempotent

List available protocol fields, optionally filtered by prefix. Supports pagination. Uses tshark -G fields (no session required).

Inputs: limit, cursor, prefix. Returns: result

file_capinfosA
Read-onlyIdempotent

Get capture file metadata including packet count, duration, file type, and optionally file hashes.

Inputs: files (required), include_hashes, machine_readable. Returns: result

file_dedupC
Idempotent

Remove duplicate packets from a capture file.

Inputs: input_file (required), output_file (required), window, ignore_bytes, +2 more. Returns: result

file_detect_typeB
Read-onlyIdempotent

Identify the format of a capture file (pcap, pcapng, etc.).

Inputs: file_path (required). Returns: result

file_mergeA
Idempotent

Merge two or more capture files into one. 'merge' interleaves by timestamp, 'concat' appends sequentially.

Inputs: inputs (required), output_file (required), mode, snaplen, +1 more. Returns: result

file_retimeC
Idempotent

Adjust packet timestamps in a capture file.

Inputs: input_file (required), output_file (required), adjust_sec, replacements, +1 more. Returns: result

file_sliceB
Idempotent

Extract packets from a capture file by packet number ranges or time window.

Inputs: input_file (required), output_file (required), snaplen, end_time, +3 more. Returns: result

file_tshark_exportA
Idempotent

Export packet data in structured format (fields, json, or ek). For writing filtered pcap files, use file_write_filtered_capture instead.

Inputs: format (required), input_file (required), fields, decode_as, +4 more. Returns: result

file_write_filtered_captureA
Idempotent

Filter packets by display filter and write matching frames to a new capture file. Unlike file_slice (packet ranges), this filters by protocol content.

Inputs: input_file (required), output_file (required), display_filter (required), decode_as, +2 more. Returns: result

filter_completeA
Read-onlyIdempotent

Auto-complete display filter field names. Requires an active analysis session (sharkd command).

Inputs: field_prefix (required), analysis_session_id (required). Returns: result

filter_validate_captureA
Read-onlyIdempotent

Validate a BPF capture filter expression for a specific interface. The interface is required because filter compilation depends on the link type.

Inputs: interface (required), capture_filter (required). Returns: result

filter_validate_displayA
Read-onlyIdempotent

Validate a Wireshark display filter expression. Returns whether the filter syntax is valid. Does not require an active analysis session.

Inputs: display_filter (required). Returns: result

ws_runtime_infoA
Read-onlyIdempotent

Get Wireshark runtime information: installed binaries, versions, available features, and allowed file roots.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 38 tools

    Disambiguation4/5

    Tools are grouped by prefixes (capture_, file_, analysis_, etc.) and most have distinct purposes. Minor overlaps like file_detect_type vs file_capinfos or analysis_get_statistics vs analysis_iograph are clarified by detailed descriptions, but a few boundaries could still be fuzzy for an agent.

    Naming Consistency3/5

    The tool names mostly follow a prefix + verb_noun pattern (e.g., capture_list_interfaces, filter_validate_display), but there are deviations like file_capinfos, analysis_catalog, and analysis_iograph that are noun-based or less conventional. This inconsistency, while readable, prevents a higher score.

    Tool Count2/5

    With 38 tools, the server is well beyond the 25-tool threshold and feels overly heavy. Although Wireshark is feature-rich, such a large surface increases agent navigation complexity and decision overhead, making it borderline unwieldy.

    Completeness5/5

    The tool set provides broad coverage across capture management, file processing, filter validation, field inspection, analysis sessions, protocol-specific lists, and artifact download. It supports the core Wireshark workflows effectively, with no significant dead ends or missing lifecycle steps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers