MCPHawk
STDIOMCP协议流量日志监控解决方案
MCP协议流量日志监控解决方案
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:
query_traffic, search_traffic, get_stats, list_methods| 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
| 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 captures unencrypted MCP traffic only. It cannot decrypt:
This tool is ideal for:
# Install from PyPI pip install mcphawk # Or install directly from GitHub pip install git+https://github.com/tech4242/mcphawk.git
sudo for packet capture (standard for network sniffers)# 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
MCPHawk includes a built-in MCP server, allowing you to query captured traffic through the Model Context Protocol itself. This creates powerful possibilities:
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 |
get_stats | Get traffic statistics | None |
list_methods | List unique JSON-RPC methods | None |
The HTTP transport uses Server-Sent Events (SSE) for streaming responses:
# Start MCP server mcphawk mcp --transport http --mcp-port 8765 # Initialize session (note: returns SSE stream) curl -N -X POST http://localhost:8765/mcp \ -H 'Accept: text/event-stream' \ -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' # Example response (SSE format): # event: message # data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
For Claude Desktop integration:
{ "mcpServers": { "mcphawk": { "command": "mcphawk", "args": ["mcp", "--transport", "stdio"] } } }
The stdio transport follows the standard MCP communication pattern:
initialize requestinitialized notificationSee examples/mcp_sdk_client.py for HTTP client example or examples/stdio_client.py for stdio communication.
sudo) on macOS/Linux for packet capturePermission Denied Error:
# On macOS/Linux, use sudo: sudo mcphawk web --auto-detect
No Traffic Captured:
--auto-detectSSE/HTTP Responses Not Showing:
--debugVote for features by opening a GitHub issue!
... and a few more off the deep end:
# Set up Python environment python3 -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install backend dependencies pip3 install -r requirements-dev.txt pip3 install -e . # Install frontend dependencies and build cd frontend npm install npm run build cd .. # Run tests python3 -m pytest -v
# Option 1: Use make (recommended) make dev # Runs both frontend and backend # Option 2: Run separately # Terminal 1 - Frontend with hot reload cd frontend && npm run dev # Terminal 2 - Backend mcphawk web --port 3000 # Option 3: Watch mode cd frontend && npm run build:watch # Auto-rebuild on changes mcphawk web --port 3000 # In another terminal