TShark MCP Server

An MCP (Model Context Protocol) server that exposes TShark as tools for AI-assisted network packet analysis. Supports PCAP analysis, live capture, TLS decryption, and telecom / SS7 signaling protocols.

Requirements

• Python 3.10+
• Wireshark / TShark installed on the system
• mergecap (bundled with Wireshark, required for merge_pcap_files)

Installation

# Recommended — installs into an isolated env and puts the
# tshark-mcp / tshark-mcp-http commands on your PATH.
uv tool install tshark-mcp

# With Windows service support (Windows only).
uv tool install "tshark-mcp[windows-service]"

# Or into a project venv:
uv pip install tshark-mcp

From a local source build (in the project root):

uv build
uv tool install --reinstall ".\dist\tshark_mcp-1.0.0-py3-none-any.whl[windows-service]"

Verify the commands are on PATH:

Get-Command tshark-mcp, tshark-mcp-http, tshark-mcp-win-service | Select-Object Name, Source

Uninstall the system installation (after removing the Windows service if any — see below):

uv tool uninstall tshark-mcp

After install you have three console scripts:

Command	Default	What it does
tshark-mcp	stdio	Run via MCP client (Claude Code / VS Code) — client manages the process
tshark-mcp-http	HTTP on 127.0.0.1:8100	Standalone HTTP server (WSL, remote, shared)
tshark-mcp-win-service	Windows service	Register as a Windows service (auto-start at boot)

Running modes

STDIO — managed by your MCP client

The MCP client launches tshark-mcp as a child process. You don't run anything manually. Just configure the client.

Claude Code — .mcp.json (project) or ~/.claude.json (user):

{
  "mcpServers": {
    "tshark-mcp": {
      "type": "stdio",
      "command": "tshark-mcp"
    }
  }
}

Or via CLI:

claude mcp add tshark-mcp -- tshark-mcp

VS Code — .vscode/mcp.json (project) or your user mcp.json:

{
  "servers": {
    "tshark-mcp": {
      "type": "stdio",
      "command": "tshark-mcp"
    }
  }
}

If tshark-mcp is not on PATH (you installed via uv pip install instead of uv tool install), replace command: "tshark-mcp" with command: "uv", args: ["tool", "run", "tshark-mcp"].

HTTP — standalone server

You start the server yourself; clients connect to its URL. Stays running across client restarts and can be shared by multiple clients.

# Default 127.0.0.1:8100, endpoint /mcp
tshark-mcp-http

# Custom host/port
tshark-mcp-http --host 0.0.0.0 --port 9000

# Use a config file (see Configuration below)
tshark-mcp-http --config /path/to/config.toml

The endpoint URL is http://<host>:<port>/mcp.

Claude Code:

{
  "mcpServers": {
    "tshark-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8100/mcp"
    }
  }
}

Or via CLI:

claude mcp add --transport http tshark-mcp http://127.0.0.1:8100/mcp

VS Code:

{
  "servers": {
    "tshark-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8100/mcp"
    }
  }
}

WSL: run the HTTP server inside WSL and point Windows-side Claude Code / VS Code at http://127.0.0.1:8100/mcp — WSL2 forwards localhost automatically.

Windows service — auto-start at boot

Register tshark-mcp-http as a Windows service. Survives reboots, runs in the background under LocalSystem. All commands below need an elevated PowerShell (admin).

pywin32 expects options BEFORE the verb (install/start/stop/remove). tshark-mcp-win-service install --startup auto is wrong — it must be --startup auto install.

Install + start:

tshark-mcp-win-service --startup auto install
tshark-mcp-win-service --wait 15 start

Verify it's running:

Get-Service TsharkMcp                                  # Status should be Running
Get-NetTCPConnection -LocalPort 8100 -State Listen     # 127.0.0.1:8100 listening

Manage:

tshark-mcp-win-service stop
tshark-mcp-win-service restart        # reload after editing config.toml

Uninstall the service only:

tshark-mcp-win-service stop
tshark-mcp-win-service remove

Full cleanup (service + uv tool + leftover pywin32 DLLs):

# 1. Remove the service (admin PS)
tshark-mcp-win-service stop
tshark-mcp-win-service remove

# 2. Uninstall the uv tool venv (admin not required)
uv tool uninstall tshark-mcp

# 3. Optional — pywin32 leaves two DLLs in the uv-managed Python dir.
#    Only remove these if no other pywin32-using uv tool is installed.
$pyDir = "$env:APPDATA\uv\python\cpython-3.13-windows-x86_64-none"
Remove-Item -Force -ErrorAction SilentlyContinue `
    "$pyDir\pywintypes313.dll", "$pyDir\pythoncom313.dll"

Because Windows services don't receive command-line arguments, configure the service via:

• Config file at %PROGRAMDATA%\tshark-mcp\config.toml (recommended) — restart the service after editing
• System-wide environment variables (TSHARK_MCP_HOST, TSHARK_MCP_PORT, TSHARK_PATH, …)

Once running, point your MCP client at http://127.0.0.1:8100/mcp exactly as in the HTTP section above.

Configuration

Configuration is layered — later sources override earlier ones:

built-in defaults  <  config file (TOML)  <  environment variables  <  CLI arguments

Config file (TOML)

Search order (first match wins):

1. --config <path> CLI argument
2. TSHARK_MCP_CONFIG environment variable
3. Windows: %APPDATA%\tshark-mcp\config.toml, then %PROGRAMDATA%\tshark-mcp\config.toml
4. Linux/macOS: $XDG_CONFIG_HOME/tshark-mcp/config.toml (or ~/.config/tshark-mcp/config.toml), then /etc/tshark-mcp/config.toml

Full schema (also see config.example.toml):

[server]
# stdio | http | streamable-http | sse
# "http" is an alias for "streamable-http" (the current MCP HTTP transport).
# "sse" is the deprecated MCP HTTP+SSE transport; kept for legacy clients.
transport = "http"
host = "127.0.0.1"
port = 8100

# Optional endpoint paths (default to FastMCP defaults)
# mount_path = "/"
# streamable_http_path = "/mcp"
# sse_path = "/sse"
# message_path = "/messages"

[tshark]
# Override tshark binary location (otherwise auto-detected).
# path = "C:\\Program Files\\Wireshark\\tshark.exe"

Environment variables

Variable	Maps to
TSHARK_MCP_CONFIG	Path to TOML config file
TSHARK_MCP_TRANSPORT	[server] transport
TSHARK_MCP_HOST	[server] host
TSHARK_MCP_PORT	[server] port
TSHARK_MCP_MOUNT_PATH	[server] mount_path
TSHARK_MCP_STREAMABLE_HTTP_PATH	[server] streamable_http_path
TSHARK_MCP_SSE_PATH	[server] sse_path
TSHARK_MCP_MESSAGE_PATH	[server] message_path
TSHARK_PATH	[tshark] path

CLI arguments

tshark-mcp and tshark-mcp-http accept the same flags:

--config PATH                  TOML config file (overrides search paths)
--transport {stdio,http,streamable-http,sse}
--host HOST
--port PORT
--mount-path PATH
--streamable-http-path PATH    default '/mcp'
--sse-path PATH
--message-path PATH
--tshark-path PATH             tshark binary (overrides TSHARK_PATH env)

The two scripts differ only in their starting defaults — tshark-mcp starts from stdio defaults, tshark-mcp-http starts from transport=http, host=127.0.0.1, port=8100. Either way, file → env → CLI all layer on top.

TShark binary auto-detection

If [tshark] path, TSHARK_PATH, and --tshark-path are all unset, the server probes:

• Windows: C:\Program Files\Wireshark\tshark.exe, C:\Program Files (x86)\Wireshark\tshark.exe
• macOS: /usr/local/bin/tshark, /opt/homebrew/bin/tshark
• Linux: /usr/bin/tshark, /usr/sbin/tshark, /usr/local/bin/tshark

Then falls back to PATH lookup.

---

Tools (25 total)

Basic Analysis

Tool	Key Parameters	Description
analyze_pcap_file	display_filter, keylog_file, max_packets	Packet summaries with optional display filter and TLS decryption
get_packet_statistics	—	Protocol hierarchy statistics (io,phs) — shows all protocol layers present
extract_packet_details	packet_number	Full verbose detail for a specific packet (1-based index)
extract_fields	fields, display_filter, keylog_file	Extract any tshark field as tab-separated values
export_to_json	display_filter, keylog_file, max_packets	Export packets as JSON for structured analysis
run_tshark_command	command_args	Run any raw tshark command

Traffic Aggregation & Statistics

Tool	Key Parameters	Description
get_conversations	protocol	Conversation statistics — protocol: eth / ip / tcp / udp / sctp
get_flow_matrix	display_filter, top_n	Host-pair communication matrix (ip.src × ip.dst), ranked by bytes
get_traffic_timeseries	interval_seconds, display_filter	Packets and bytes per time bucket — identifies bursts and periodic patterns
aggregate_flows	group_by, display_filter, top_n	Group packets by any field combination (e.g. ip.src,tcp.dstport)

Protocol-Specific Analysis

Tool	Key Parameters	Description
analyze_dns	display_filter, top_n	DNS query patterns, NXDOMAIN detection, response time statistics
get_tcp_performance	display_filter	RTT, retransmissions, window size — diagnose network quality issues
follow_stream	protocol, stream_index, keylog_file	Reconstruct a TCP / UDP / SCTP stream as ASCII text

Telecom / SS7 Signaling

These tools handle the telecom core network signaling stack: SCTP → M3UA → SCCP → TCAP → MAP

Tool	Key Parameters	Description
reconstruct_tcap_dialogue	display_filter, max_dialogues	Group TCAP messages (Begin/Continue/End/Abort) by transaction ID (OTID/DTID)
analyze_map_operations	display_filter, top_n	MAP operation frequency table + per-IMSI activity summary

TLS Decryption

Requires a TLS key log file generated by the target application.

Tool	Description
follow_tls_stream	Reconstruct a decrypted TLS stream as plaintext from a PCAP + key log file
capture_and_decrypt	Capture live traffic and immediately show decrypted TLS content
tshark_reading_manual	Read this first — full TLS decryption workflow including debugger-based key extraction

Live Capture

Tool	Key Parameters	Description
list_interfaces	—	List available network interfaces for live capture
capture_live	interface, packet_count, duration, display_filter	Capture live packets (max 500 packets / 60 s)
capture_process	pid, interface, output_pcap, duration, keylog_file	Capture traffic for a specific process by PID

File Operations

Tool	Key Parameters	Description
filter_and_save	display_filter	Filter packets from a PCAP and save to a new PCAP file
export_objects	protocol, output_dir	Extract files transferred over HTTP / SMB / TFTP / IMF / DICOM
merge_pcap_files	input_files, output_file, display_filter	Merge multiple PCAPs in timestamp order (uses mergecap)

Process Management

Tool	Description
list_processes	List running processes with PIDs (filter by name)

---

Examples

General PCAP Analysis

# Protocol hierarchy — confirm what layers are in the capture
get_packet_statistics("/captures/traffic.pcap")

# First 100 packets, HTTP only
analyze_pcap_file("/captures/traffic.pcap", display_filter="http")

# Extract source IPs, methods, and URIs from HTTP requests
extract_fields(
    file_path="/captures/traffic.pcap",
    fields="ip.src,http.request.method,http.request.uri",
    display_filter="http.request"
)

# Full detail for packet 42
extract_packet_details("/captures/traffic.pcap", packet_number=42)

Traffic Aggregation

# Which hosts talk to each other most? (top 20 by bytes)
get_flow_matrix("/captures/traffic.pcap")

# Traffic volume over time — 5-second buckets
get_traffic_timeseries("/captures/traffic.pcap", interval_seconds=5.0)

# TCP traffic only, 1-second buckets
get_traffic_timeseries("/captures/traffic.pcap", interval_seconds=1.0, display_filter="tcp")

# Per-service breakdown: which src IP hits which dst port most?
aggregate_flows(
    file_path="/captures/traffic.pcap",
    group_by="ip.src,ip.dst,tcp.dstport",
    display_filter="tcp"
)

# SCTP conversation statistics
get_conversations("/captures/ss7.pcap", protocol="sctp")

DNS Analysis

# Top queried domains, NXDOMAIN failures, response times
analyze_dns("/captures/traffic.pcap")

# DNS from a specific client only
analyze_dns("/captures/traffic.pcap", display_filter="ip.src == 192.168.1.10")

TCP Performance Diagnosis

# RTT, retransmission rate, window size — is the network healthy?
get_tcp_performance("/captures/traffic.pcap")

# Performance for a specific server
get_tcp_performance("/captures/traffic.pcap", display_filter="ip.addr == 10.0.0.1")

Stream Reconstruction

# Follow the first TCP stream
follow_stream("/captures/traffic.pcap", protocol="tcp", stream_index=0)

# Follow an SCTP stream
follow_stream("/captures/ss7.pcap", protocol="sctp", stream_index=0)

# Follow a TELNET session (TELNET runs over TCP port 23)
follow_stream("/captures/traffic.pcap", protocol="tcp", stream_index=0)

Telecom / SS7 Signaling Analysis

The typical protocol stack is: SCTP → M3UA → SCCP → TCAP → MAP

# Step 1 — confirm SS7 layers are present
get_packet_statistics("/captures/ss7.pcap")
# Expected output includes: sctp, m3ua, mtp3, sccp, tcap, gsm_map

# Step 2 — reconstruct TCAP dialogues (Begin→Continue→End chains)
reconstruct_tcap_dialogue("/captures/ss7.pcap")

# Step 3 — MAP operation frequency + IMSI tracking
analyze_map_operations("/captures/ss7.pcap")

# Step 4 — raw MAP field extraction
extract_fields(
    file_path="/captures/ss7.pcap",
    fields="gsm_map.opr.code,gsm_map.imsi,gsm_map.msisdn.digits",
    display_filter="gsm_map"
)

# SCCP routing analysis — who calls whom?
aggregate_flows(
    file_path="/captures/ss7.pcap",
    group_by="sccp.calling_party,sccp.called_party",
    display_filter="sccp"
)

# Filter to a specific TCAP dialogue by OTID
extract_fields(
    file_path="/captures/ss7.pcap",
    fields="frame.time_relative,tcap.MessageType,tcap.otid,tcap.dtid,gsm_map.opr.code",
    display_filter="tcap.otid == aabbccdd"
)

File Extraction (Forensics)

# Extract files transferred over HTTP in a capture
export_objects(
    file_path="/captures/traffic.pcap",
    protocol="http",
    output_dir="/tmp/extracted/"
)

# Extract SMB file transfers
export_objects(
    file_path="/captures/traffic.pcap",
    protocol="smb",
    output_dir="/tmp/smb_files/"
)

Multi-PCAP Correlation

# Merge two captures from different taps, analyze combined
merge_pcap_files(
    input_files="/captures/tap1.pcap,/captures/tap2.pcap",
    output_file="/captures/merged.pcap"
)

# With a display filter on the merged result
merge_pcap_files(
    input_files="/captures/tap1.pcap,/captures/tap2.pcap",
    output_file="/captures/merged.pcap",
    display_filter="tcp"
)

TLS Decryption

# Decrypt and reconstruct HTTPS stream
follow_tls_stream(
    file_path="/captures/traffic.pcap",
    keylog_file="C:/captures/keys.log",
    stream_index=0
)

# Extract HTTP fields from decrypted traffic
extract_fields(
    file_path="/captures/traffic.pcap",
    fields="ip.src,http.request.method,http.request.uri",
    display_filter="http.request",
    keylog_file="C:/captures/keys.log"
)

# Live capture + real-time TLS decryption
capture_and_decrypt(
    interface=r"\Device\NPF_{...}",
    keylog_file="C:/captures/keys.log",
    output_pcap="C:/captures/session.pcap",
    duration=30
)

Process-Specific Capture

# Find process PID
list_processes("chrome")
# → chrome.exe  PID 4812

# Capture traffic for that process
capture_process(
    pid=4812,
    interface=r"\Device\NPF_{...}",   # from list_interfaces()
    output_pcap="C:/captures/chrome.pcap",
    duration=30
)

# Capture + decrypt TLS in one step
capture_process(
    pid=4812,
    interface=r"\Device\NPF_{...}",
    output_pcap="C:/captures/chrome.pcap",
    duration=30,
    keylog_file="C:/captures/keys.log"   # set SSLKEYLOGFILE before launching Chrome
)

---

Protocol Support Reference

Protocol	Filter	Relevant Fields	Best Tool
TCP	tcp	tcp.srcport, tcp.dstport, tcp.stream	follow_stream, get_tcp_performance
UDP	udp	udp.srcport, udp.dstport	follow_stream, get_conversations
SCTP	sctp	sctp.srcport, sctp.dstport, sctp.chunk_type	get_conversations, follow_stream
HTTP	http	http.request.uri, http.response.code	extract_fields, export_objects
TLS/HTTPS	tls	tls.record.content_type	follow_tls_stream, capture_and_decrypt
DNS	dns	dns.qry.name, dns.flags.rcode, dns.time	analyze_dns
TELNET	telnet	(follow TCP stream)	follow_stream (protocol=tcp)
M3UA	m3ua	m3ua.protocol_data_opc, m3ua.protocol_data_dpc	extract_fields, aggregate_flows
SCCP	sccp	sccp.calling_party, sccp.called_party, sccp.ssn	aggregate_flows, extract_fields
TCAP	tcap	tcap.otid, tcap.dtid, tcap.MessageType	reconstruct_tcap_dialogue
MAP	gsm_map	gsm_map.opr.code, gsm_map.imsi, gsm_map.msisdn.digits	analyze_map_operations

---

TLS Decryption Setup

TShark can decrypt TLS traffic when given the session keys written by the application. Set the SSLKEYLOGFILE environment variable before launching the target application:

# Windows
set SSLKEYLOGFILE=C:\captures\keys.log
start chrome

# Linux / macOS
export SSLKEYLOGFILE=/tmp/keys.log
google-chrome &

Supported runtimes: Chrome, Edge, Firefox, curl, Python (requests / httpx / aiohttp), Go crypto/tls (with SSLKEYLOGFILE patch), Node.js (--tls-keylog).

For applications that do not support SSLKEYLOGFILE (compiled binaries, custom TLS stacks), keys must be extracted from process memory using a debugger. Call tshark_reading_manual for the complete step-by-step workflow including x64dbg-based key extraction.

---

Process-Specific Capture — How It Works

1. list_processes — find the PID of the target process.
2. capture_process — snapshots the process's open connections at capture start, builds a BPF filter from its local ports, then runs a timed capture saving to a PCAP file.

Because the filter is derived at capture start, connections opened later still get captured if they share a port already in the filter. For long-running captures or applications with many short-lived connections, re-run capture_process as needed, or use capture_live without a filter and post-filter with filter_and_save.

Platform	Tool used internally	Notes
Windows	netstat -ano (built-in)	No extra installation needed
macOS	lsof (built-in)	No extra installation needed
Linux	ss (iproute2)	Usually pre-installed; apt install iproute2 if missing

---

Development

git clone <repository-url>
cd tshark-mcp
uv sync

# Run during development
uv run server.py                                     # stdio
uv run server.py --transport http --port 8100        # HTTP
uv run tshark-mcp-http                               # HTTP (entry-point alias)

# Tests (no TShark installation required — subprocess is mocked)
uv run python -m pytest test_server.py -v

# Build a local wheel and install it as a uv tool (Windows service ready)
uv build
uv tool install --reinstall ".\dist\tshark_mcp-1.0.0-py3-none-any.whl[windows-service]"

# Clean build artifacts
Remove-Item -Recurse -Force -ErrorAction SilentlyContinue dist, build, *.egg-info

Project Policies

• License: see LICENSE
• Contributing: see CONTRIBUTING.md
• Code of conduct: see CODE_OF_CONDUCT.md
• Security: see SECURITY.md

Release

Automated via .github/workflows/release.yml. Pushing a v* tag builds the wheel and publishes to PyPI using the PYPI_API_TOKEN repo secret:

git tag v1.2.3
git push origin v1.2.3

• Pre-release check: uv run python scripts/release_check.py
• Full release process + one-time PYPI_API_TOKEN setup: see RELEASE.md