{"id":37077700,"url":"https://github.com/tech4242/mcphawk","last_synced_at":"2026-01-14T09:00:50.531Z","repository":{"id":308190635,"uuid":"1023074650","full_name":"tech4242/mcphawk","owner":"tech4242","description":"MCPHawk is a new Logging \u0026 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.","archived":false,"fork":false,"pushed_at":"2025-12-27T22:54:47.000Z","size":4458,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-30T00:51:01.721Z","etag":null,"topics":["ai","logging","mcp","monitoring","networking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tech4242.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-20T13:25:46.000Z","updated_at":"2025-10-20T14:54:38.000Z","dependencies_parsed_at":"2025-08-04T19:40:21.400Z","dependency_job_id":null,"html_url":"https://github.com/tech4242/mcphawk","commit_stats":null,"previous_names":["tech4242/mcphawk"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/tech4242/mcphawk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fmcphawk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fmcphawk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fmcphawk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fmcphawk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tech4242","download_url":"https://codeload.github.com/tech4242/mcphawk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tech4242%2Fmcphawk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","logging","mcp","monitoring","networking"],"created_at":"2026-01-14T09:00:49.707Z","updated_at":"2026-01-14T09:00:50.518Z","avatar_url":"https://github.com/tech4242.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"examples/branding/mcphawk_logo.png\" alt=\"MCPHawk Logo\" height=\"130\"\u003e\n  \n  [![CI](https://github.com/tech4242/mcphawk/actions/workflows/ci.yml/badge.svg)](https://github.com/tech4242/mcphawk/actions/workflows/ci.yml)\n  [![codecov](https://codecov.io/gh/tech4242/mcphawk/branch/main/graph/badge.svg)](https://codecov.io/gh/tech4242/mcphawk)\n  [![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n  [![Typer](https://img.shields.io/badge/CLI-Typer-informational?style=flat\u0026logo=python\u0026color=2bbc8a)](https://typer.tiangolo.com/)\n  [![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat\u0026logo=fastapi)](https://fastapi.tiangolo.com/)\n  [![Vue.js](https://img.shields.io/badge/vue.js-3.x-brightgreen.svg)](https://vuejs.org/)\n  [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n  [![PEP8](https://img.shields.io/badge/code%20style-pep8-orange.svg)](https://www.python.org/dev/peps/pep-0008/)\n  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\u003c/div\u003e\n\nMCPHawk is a new Logging \u0026 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.\n\n**Key Capabilities:**\n- **Protocol-Aware Capture**: Understands MCP's JSON-RPC 2.0 transport layer, capturing and reassembling messages from stdio pipes and HTTP streams\n- **Transport Agnostic**: Monitors MCP traffic across all standard transports (stdio, HTTP Streaming, HTTP+SSE)\n- **Full Message Reconstruction**: Advanced stream reassembly handles fragmented packets, chunked HTTP transfers, SSE streams, and stdio pipes\n\n\u003cimg src=\"examples/branding/mcphawk_screenshot.png\" alt=\"MCPHawk Screenshot\" width=\"100%\"\u003e\n\n## Core Features\n\n### 🔍 MCP Protocol Analysis\n- **Complete JSON-RPC 2.0 Support**: Correctly identifies and categorizes all MCP message types\n  - **Requests**: Method calls with unique IDs for correlation\n  - **Responses**: Success results and error responses with matching IDs  \n  - **Notifications**: Fire-and-forget method calls without IDs\n  - **Batch Operations**: Support for JSON-RPC batch requests/responses\n- **Transport-Specific Handling**: See MCP Transport Support table below for full details\n  - **Chunked Transfer**: Handles HTTP chunked transfer encoding transparently\n- **Protocol Compliance**: Validates JSON-RPC 2.0 structure and MCP-specific extensions\n\n### 🚀 Advanced Capture Capabilities\n- **Auto-Discovery Mode**: Intelligently detects MCP traffic on any port using pattern matching\n- **TCP Stream Reassembly**: Reconstructs complete messages from fragmented packets\n- **Multi-Stream Tracking**: Simultaneously monitors multiple MCP client-server connections\n- **IPv4/IPv6 Dual Stack**: Native support for both IP protocols\n- **Zero-Copy Architecture**: Efficient packet processing without client/server overhead\n\n### 📊 Analysis \u0026 Visualization\n- **Real-Time Web Dashboard**: Live traffic visualization with WebSocket updates\n- **Message Flow Visualization**: Track request-response pairs using JSON-RPC IDs\n- **Traffic Statistics**: Method frequency, error rates, response times\n- **Search \u0026 Filter**: Query by method name, message type, content patterns\n- **Export Capabilities**: Save captured sessions for offline analysis\n\n### 🛠️ Developer Experience\n- **MCP Server Integration**: Query captured data using MCP protocol itself\n  - FastMCP-based implementation for maximum compatibility\n  - Available tools: `query_traffic`, `search_traffic`, `get_stats`, `list_methods`\n  - Supports both stdio and HTTP transports\n- **Multiple Interfaces**:\n  - Web UI for interactive exploration\n  - CLI for scripting and automation  \n  - MCP server for programmatic access\n- **Flexible Deployment**:\n  - Standalone sniffer mode\n  - Integrated web + sniffer\n  - Historical log analysis without active capture\n\n### MCP Transport Support\n\n| Official MCP Transport | Protocol Version | Capture Support | Details |\n|------------------------|------------------|:---------------:|---------|\n| **stdio** | All versions | ✅ Full | Process wrapper transparently captures stdin/stdout between client and server |\n| **HTTP Streaming** | 2025-03-26+ | ✅ Full | HTTP POST with optional SSE streaming responses |\n| **HTTP+SSE** (deprecated) | 2024-11-05 | ✅ Full | Legacy transport with separate SSE endpoint |\n\nNote: Raw TCP traffic with JSON-RPC is also captured and marked as \"unknown\" transport type\n\n## Comparison with Similar Tools\n\n| Feature                                      | MCPHawk | mcpinspector | Wireshark |\n|-----------------------------------------------|:---------:|:------------:|:---------:|\n| Passive sniffing (no proxy needed)            |     ✅     |      ❌       |     ✅     |\n| MCP/JSON-RPC protocol awareness               |     ✅     |      ✅       |     ❌     |\n| SSE/Chunked HTTP support                      |     ✅     |      ❓       |     ❌     |\n| TCP stream reassembly                         |     ✅     |      ❌       |     ✅     |\n| Auto-detect MCP traffic                       |     ✅     |      ❌       |     ❌     |\n| Web UI for live/historical traffic            |     ✅     |      ✅       |     ❌     |\n| JSON-RPC message type detection               |     ✅     |      ❌       |     ❌     |\n| MCP server for data access                    |     ✅     |      ❌       |     ❌     |\n| No client/server config needed                |     ✅     |      ❌       |     ✅     |\n| Interactive testing/debugging                 |     ❌     |      ✅       |     ❌     |\n| Proxy/MITM capabilities                       |     ✅ (stdio)     |      ✅       |     ❌     |\n\n**When to use each tool:**\n- **MCPHawk**: Passive monitoring, protocol analysis, debugging MCP implementations, understanding traffic patterns\n- **mcpinspector**: Active testing, crafting requests, interactive debugging with proxy\n- **Wireshark**: General network analysis, non-MCP protocols, packet-level inspection\n\n## TLS/HTTPS Limitations\n\nMCPHawk captures **unencrypted** MCP traffic only. It cannot decrypt:\n- HTTPS/WSS (WebSocket Secure) connections\n- TLS-encrypted TCP connections\n- Any SSL/TLS encrypted traffic\n\n**This tool is ideal for:**\n- 🛠️ **Local MCP development** - Debug your MCP server implementations\n- 🔍 **Understanding MCP protocol** - See actual JSON-RPC message flow\n- 🐛 **Troubleshooting local tools** - Monitor Claude Desktop, Cline, etc. with YOUR local MCP servers\n- 📊 **Development/staging environments** - Where TLS is often disabled\n\n## Installation\n\n### For Users\n\n```bash\n# Install from PyPI\npip install mcphawk\n\n# Or install directly from GitHub\npip install git+https://github.com/tech4242/mcphawk.git\n```\n\n### Requirements\n\n- **macOS/Linux**: Requires `sudo` for packet capture (standard for network sniffers)\n- **Python**: 3.9 or higher\n- **Permissions**: Must run with elevated privileges to access network interfaces\n\n### Quick Start\n\n```bash\n# Get help\nmcphawk --help\n\n# Get help for specific command\nmcphawk sniff --help\nmcphawk web --help\n\n# Start web UI with auto-detect mode (requires sudo on macOS)\nsudo mcphawk web --auto-detect\n\n# Monitor MCP traffic on a specific port (console output)\nsudo mcphawk sniff --port 3000\n\n# Monitor multiple ports with a custom filter\nsudo mcphawk sniff --filter \"tcp port 3000 or tcp port 8080\"\n\n# Auto-detect MCP traffic on any port\nsudo mcphawk sniff --auto-detect\n\n# Start web UI with sniffer on specific port\nsudo mcphawk web --port 3000\n\n# Start web UI with custom filter for multiple ports\nsudo mcphawk web --filter \"tcp port 3000 or tcp port 8080\"\n\n# View historical logs only (no active sniffing)\nsudo mcphawk web --no-sniffer\n\n# Custom web server configuration\nsudo mcphawk web --port 3000 --host 0.0.0.0 --web-port 9000\n\n# Enable debug output for troubleshooting\nsudo mcphawk sniff --port 3000 --debug\nsudo mcphawk web --port 3000 --debug\n\n# Wrap an MCP server to capture stdio traffic\nmcphawk wrap /path/to/mcp-server --arg1 --arg2\n\n# Example: Wrap Context7 MCP server to monitor Claude Desktop's documentation lookups\nmcphawk wrap npx -y @upstash/context7-mcp@latest\n\n# Claude Desktop config to use the wrapped version:\n# {\n#   \"mcpServers\": {\n#     \"context7\": {\n#       \"command\": \"mcphawk\",\n#       \"args\": [\"wrap\", \"npx\", \"-y\", \"@upstash/context7-mcp@latest\"]\n#     }\n#   }\n# }\n\n# Start MCP server with Streamable HTTP transport (default)\nmcphawk mcp --transport http --mcp-port 8765\n\n# Start MCP server with stdio transport (for Claude Desktop integration)\nmcphawk mcp --transport stdio\n\n# Start sniffer with integrated MCP server (HTTP transport)\nsudo mcphawk sniff --port 3000 --with-mcp --mcp-transport http\n\n# Start web UI with integrated MCP server\nsudo mcphawk web --port 3000 --with-mcp --mcp-transport http --mcp-port 8765\n```\n\n## MCP Server Integration\n\nMCPHawk includes a built-in MCP server, allowing you to query captured traffic through the Model Context Protocol itself. This creates powerful possibilities:\n\n- **AI-Powered Analysis**: Connect Claude or other LLMs to analyze traffic patterns\n- **Automated Monitoring**: Build agents that detect anomalies or specific behaviors\n- **Integration Testing**: Programmatically verify MCP interactions in CI/CD pipelines\n\n\u003cimg src=\"examples/branding/mcphawk_claudedesktop.png\" alt=\"MCPHawk Claude Desktop MCP\" width=\"100%\"\u003e\n\n### Available Tools\n\nThe MCP server exposes these tools for traffic analysis:\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `query_traffic` | Fetch captured logs with pagination | `limit`, `offset` |\n| `get_log` | Retrieve specific log entry | `log_id` |\n| `search_traffic` | Search logs by content or type | `search_term`, `message_type`, `traffic_type`, `limit` |\n| `get_stats` | Get traffic statistics | None |\n| `list_methods` | List unique JSON-RPC methods | None |\n\n### Transport Options\n\n#### HTTP Transport (Development \u0026 Testing)\n\nThe HTTP transport uses Server-Sent Events (SSE) for streaming responses:\n\n```bash\n# Start MCP server\nmcphawk mcp --transport http --mcp-port 8765\n\n# Initialize session (note: returns SSE stream)\ncurl -N -X POST http://localhost:8765/mcp \\\n  -H 'Accept: text/event-stream' \\\n  -d '{\"jsonrpc\":\"2.0\",\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}},\"id\":1}'\n\n# Example response (SSE format):\n# event: message\n# data: {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"protocolVersion\":\"2024-11-05\",...}}\n```\n\n#### stdio Transport (Production \u0026 Claude Desktop)\n\nFor Claude Desktop integration:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcphawk\": {\n      \"command\": \"mcphawk\",\n      \"args\": [\"mcp\", \"--transport\", \"stdio\"]\n    }\n  }\n}\n```\n\nThe stdio transport follows the standard MCP communication pattern:\n1. Client sends `initialize` request\n2. Server responds with capabilities\n3. Client sends `initialized` notification\n4. Normal tool calls can proceed\n\nSee [examples/mcp_sdk_client.py](examples/mcp_sdk_client.py) for HTTP client example or [examples/stdio_client.py](examples/stdio_client.py) for stdio communication.\n\n## Platform Support\n\n### Tested Platforms\n- ✅ **macOS** (Apple Silicon \u0026 Intel) - Fully tested\n- ✅ **Linux** (Ubuntu, Debian) - Fully tested  \n- ⚠️  **Windows** - Experimental (Scapy should work but untested)\n\n### Known Limitations\n\n- Requires elevated privileges (`sudo`) on macOS/Linux for packet capture\n- Limited to localhost/loopback interface monitoring\n- Cannot decrypt TLS/HTTPS traffic (WSS, HTTPS)\n- IPv6 support requires explicit interface configuration on some systems\n- High traffic volumes (\u003e1000 msgs/sec) may impact performance\n\n### Troubleshooting\n\n**Permission Denied Error:**\n```bash\n# On macOS/Linux, use sudo:\nsudo mcphawk web --auto-detect\n```\n\n**No Traffic Captured:**\n- Ensure the MCP server/client is using localhost (127.0.0.1 or ::1)\n- Check if traffic is on the expected port\n- Try auto-detect mode to find MCP traffic: `--auto-detect`\n- Verify traffic is unencrypted (not HTTPS/TLS)\n- On macOS, ensure Terminal has permission to capture packets in System Preferences\n\n**SSE/HTTP Responses Not Showing:**\n- Confirm the server uses standard SSE format (event: message\\ndata: {...}\\n\\n)\n- Check if responses use chunked transfer encoding\n- Enable debug mode to see detailed packet analysis: `--debug`\n\n## Potential Upcoming Features\n\nVote for features by opening a GitHub issue!\n\n- [x] **Auto-detect MCP traffic** - Automatically discover MCP traffic on any port without prior configuration\n- [x] **MCP Server Interface** - Expose captured traffic via MCP server for AI agents to query and analyze traffic patterns\n- [x] **Stdio capture** - Transparent process wrapper to capture stdin/stdout communication\n- [ ] **Protocol Version Detection** - Identify and display MCP protocol version from captured traffic\n- [ ] **Smart Search \u0026 Filtering** - Search by method name, params, or any JSON field with regex support\n- [ ] **Performance Analytics** - Request/response timing, method frequency charts, and latency distribution\n- [ ] **Export \u0026 Share** - Export sessions as JSON/CSV, generate shareable links, create HAR-like files\n- [ ] **Test Generation** - Auto-generate test cases from captured traffic\n- [ ] **Error Analysis** - Highlight errors, group similar issues, show error trends\n- [ ] **Session Management** - Save/load capture sessions, compare sessions side-by-side\n- [ ] **Interactive Replay** - Click any request to re-send it, edit and replay captured messages\n- [ ] **Real-time Alerts** - Alert on specific methods or error patterns with webhook support\n- [ ] **Visualization** - Sequence diagrams, resource heat maps, method dependency graphs\n\n... and a few more off the deep end:\n- [ ] **TLS/HTTPS Support (MITM Proxy Mode)** - Optional man-in-the-middle proxy with certificate installation for encrypted traffic\n- [ ] **External Decryption Integration** - Import decrypted streams from Wireshark, Chrome DevTools, or SSLKEYLOGFILE\n\n## For Developers\n\n```bash\n# Set up Python environment\npython3 -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install backend dependencies\npip3 install -r requirements-dev.txt\npip3 install -e .\n\n# Install frontend dependencies and build\ncd frontend\nnpm install\nnpm run build\ncd ..\n\n# Run tests\npython3 -m pytest -v\n```\n\n### Some Vue options:\n\n```bash\n# Option 1: Use make (recommended)\nmake dev  # Runs both frontend and backend\n\n# Option 2: Run separately\n# Terminal 1 - Frontend with hot reload\ncd frontend \u0026\u0026 npm run dev\n\n# Terminal 2 - Backend\nmcphawk web --port 3000\n\n# Option 3: Watch mode\ncd frontend \u0026\u0026 npm run build:watch  # Auto-rebuild on changes\nmcphawk web --port 3000           # In another terminal\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftech4242%2Fmcphawk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftech4242%2Fmcphawk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftech4242%2Fmcphawk/lists"}