</div>

MCPHawk is a new Logging & Monitoring solution for Model Context Protocol (MCP) traffic, providing deep visibility into MCP client-server interactions. It started off as a mix between Wireshark and mcpinspector, purpose-built for the MCP ecosystem, and is now slowly turning into something more.

Key Capabilities:

Protocol-Aware Capture: Understands MCP's JSON-RPC 2.0 transport layer, capturing and reassembling messages from stdio pipes and HTTP streams
Transport Agnostic: Monitors MCP traffic across all standard transports (stdio, HTTP Streaming, HTTP+SSE)
Full Message Reconstruction: Advanced stream reassembly handles fragmented packets, chunked HTTP transfers, SSE streams, and stdio pipes

Core Features

🔍 MCP Protocol Analysis

Complete JSON-RPC 2.0 Support: Correctly identifies and categorizes all MCP message types
- Requests: Method calls with unique IDs for correlation
- Responses: Success results and error responses with matching IDs
- Notifications: Fire-and-forget method calls without IDs
- Batch Operations: Support for JSON-RPC batch requests/responses
Transport-Specific Handling: See MCP Transport Support table below for full details
- Chunked Transfer: Handles HTTP chunked transfer encoding transparently
Protocol Compliance: Validates JSON-RPC 2.0 structure and MCP-specific extensions

🚀 Advanced Capture Capabilities

Auto-Discovery Mode: Intelligently detects MCP traffic on any port using pattern matching
TCP Stream Reassembly: Reconstructs complete messages from fragmented packets
Multi-Stream Tracking: Simultaneously monitors multiple MCP client-server connections
IPv4/IPv6 Dual Stack: Native support for both IP protocols
Zero-Copy Architecture: Efficient packet processing without client/server overhead

📊 Analysis & Visualization

Real-Time Web Dashboard: Live traffic visualization with WebSocket updates
Message Flow Visualization: Track request-response pairs using JSON-RPC IDs
Traffic Statistics: Method frequency, error rates, response times
Search & Filter: Query by method name, message type, content patterns
Export Capabilities: Save captured sessions for offline analysis

🛠️ Developer Experience

MCP Server Integration: Query captured data using MCP protocol itself
- FastMCP-based implementation for maximum compatibility
- Available tools: query_traffic, search_traffic, get_stats, list_methods
- Supports both stdio and HTTP transports
Multiple Interfaces:
- Web UI for interactive exploration
- CLI for scripting and automation
- MCP server for programmatic access
Flexible Deployment:
- Standalone sniffer mode
- Integrated web + sniffer
- Historical log analysis without active capture

MCP Transport Support

| Official MCP Transport | Protocol Version | Capture Support | Details | |------------------------|------------------|:---------------:|---------| | stdio | All versions | ✅ Full | Process wrapper transparently captures stdin/stdout between client and server | | HTTP Streaming | 2025-03-26+ | ✅ Full | HTTP POST with optional SSE streaming responses | | HTTP+SSE (deprecated) | 2024-11-05 | ✅ Full | Legacy transport with separate SSE endpoint |

Note: Raw TCP traffic with JSON-RPC is also captured and marked as "unknown" transport type

Comparison with Similar Tools

| Feature | MCPHawk | mcpinspector | Wireshark | |-----------------------------------------------|:---------:|:------------:|:---------:| | Passive sniffing (no proxy needed) | ✅ | ❌ | ✅ | | MCP/JSON-RPC protocol awareness | ✅ | ✅ | ❌ | | SSE/Chunked HTTP support | ✅ | ❓ | ❌ | | TCP stream reassembly | ✅ | ❌ | ✅ | | Auto-detect MCP traffic | ✅ | ❌ | ❌ | | Web UI for live/historical traffic | ✅ | ✅ | ❌ | | JSON-RPC message type detection | ✅ | ❌ | ❌ | | MCP server for data access | ✅ | ❌ | ❌ | | No client/server config needed | ✅ | ❌ | ✅ | | Interactive testing/debugging | ❌ | ✅ | ❌ | | Proxy/MITM capabilities | ✅ (stdio) | ✅ | ❌ |

When to use each tool:

MCPHawk: Passive monitoring, protocol analysis, debugging MCP implementations, understanding traffic patterns
mcpinspector: Active testing, crafting requests, interactive debugging with proxy
Wireshark: General network analysis, non-MCP protocols, packet-level inspection

TLS/HTTPS Limitations

MCPHawk captures unencrypted MCP traffic only. It cannot decrypt:

HTTPS/WSS (WebSocket Secure) connections
TLS-encrypted TCP connections
Any SSL/TLS encrypted traffic

This tool is ideal for:

🛠️ Local MCP development - Debug your MCP server implementations
🔍 Understanding MCP protocol - See actual JSON-RPC message flow
🐛 Troubleshooting local tools - Monitor Claude Desktop, Cline, etc. with YOUR local MCP servers
📊 Development/staging environments - Where TLS is often disabled

Installation

For Users

# Install from PyPI
pip install mcphawk

# Or install directly from GitHub
pip install git+https://github.com/tech4242/mcphawk.git

Requirements

macOS/Linux: Requires sudo for packet capture (standard for network sniffers)
Python: 3.9 or higher
Permissions: Must run with elevated privileges to access network interfaces

Quick Start

# Get help
mcphawk --help

# Get help for specific command
mcphawk sniff --help
mcphawk web --help

# Start web UI with auto-detect mode (requires sudo on macOS)
sudo mcphawk web --auto-detect

# Monitor MCP traffic on a specific port (console output)
sudo mcphawk sniff --port 3000

# Monitor multiple ports with a custom filter
sudo mcphawk sniff --filter "tcp port 3000 or tcp port 8080"

# Auto-detect MCP traffic on any port
sudo mcphawk sniff --auto-detect

# Start web UI with sniffer on specific port
sudo mcphawk web --port 3000

# Start web UI with custom filter for multiple ports
sudo mcphawk web --filter "tcp port 3000 or tcp port 8080"

# View historical logs only (no active sniffing)
sudo mcphawk web --no-sniffer

# Custom web server configuration
sudo mcphawk web --port 3000 --host 0.0.0.0 --web-port 9000

# Enable debug output for troubleshooting
sudo mcphawk sniff --port 3000 --debug
sudo mcphawk web --port 3000 --debug

# Wrap an MCP server to capture stdio traffic
mcphawk wrap /path/to/mcp-server --arg1 --arg2

# Example: Wrap Context7 MCP server to monitor Claude Desktop's documentation lookups
mcphawk wrap npx -y @upstash/context7-mcp@latest

# Claude Desktop config to use the wrapped version:
# {
#   "mcpServers": {
#     "context7": {
#       "command": "mcphawk",
#       "args": ["wrap", "npx", "-y", "@upstash/context7-mcp@latest"]
#     }
#   }
# }

# Start MCP server with Streamable HTTP transport (default)
mcphawk mcp --transport http --mcp-port 8765

# Start MCP server with stdio transport (for Claude Desktop integration)
mcphawk mcp --transport stdio

# Start sniffer with integrated MCP server (HTTP transport)
sudo mcphawk sniff --port 3000 --with-mcp --mcp-transport http

# Start web UI with integrated MCP server
sudo mcphawk web --port 3000 --with-mcp --mcp-transport http --mcp-port 8765

MCP Server Integration

MCPHawk includes a built-in MCP server, allowing you to query captured traffic through the Model Context Protocol itself. This creates powerful possibilities:

AI-Powered Analysis: Connect Claude or other LLMs to analyze traffic patterns
Automated Monitoring: Build agents that detect anomalies or specific behaviors
Integration Testing: Programmatically verify MCP interactions in CI/CD pipelines

Available Tools

The MCP server exposes these tools for traffic analysis:

| Tool | Description | Parameters | |------|-------------|------------| | query_traffic | Fetch captured logs with pagination | limit, offset | | get_log | Retrieve specific log entry | log_id | | search_traffic | Search logs by content or type | search_term, message_type, traffic_type, limit |

Mcphawk

Install / Use

README