mcp-reticle

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/labterminal/mcp-reticle/main/frontend/src/assets/logo-white.png" /> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/labterminal/mcp-reticle/main/frontend/src/assets/logo.png" /> <img src="https://raw.githubusercontent.com/labterminal/mcp-reticle/main/frontend/src/assets/logo.png" alt="Reticle Logo" width="120" /> </picture> </p> <h1 align="center">RETICLE</h1> <p align="center"> <strong>The Wireshark for the Model Context Protocol (MCP)</strong> </p> <p align="center"> <a href="LICENSE"> <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /> </a> <a href="https://www.npmjs.com/package/mcp-reticle"> <img src="https://img.shields.io/npm/v/mcp-reticle.svg" alt="npm" /> </a> <a href="https://pypi.org/project/mcp-reticle/"> <img src="https://img.shields.io/pypi/v/mcp-reticle.svg" alt="PyPI" /> </a> <a href="https://github.com/labterminal/mcp-reticle/wiki"> <img src="https://img.shields.io/badge/docs-wiki-informational" alt="Docs (Wiki)" /> </a> <img src="https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg" alt="Platform" /> </p> <p align="center"> <em>See what your agent sees.</em> </p> <p align="center"> Reticle intercepts, visualizes, and profiles MCP JSON-RPC traffic in real time — designed for microsecond-level overhead. </p> <p align="center"> <a href="#quick-start">Quick start</a> · <a href="#installation">Install</a> · <a href="#documentation">Docs</a> · <a href="#security--privacy">Security</a> · <a href="#contributing">Contributing</a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/labterminal/mcp-reticle/main/frontend/src/styles/reticle.png" alt="Reticle Screenshot" width="900" /> </p> --- ## What is Reticle? Reticle is a proxy + UI for debugging MCP integrations: - inspect raw JSON-RPC messages (requests / notifications / responses) - correlate request ↔ response instantly - profile latency and token estimates - capture server stderr and crashes - record sessions and export logs Supported transports: **stdio**, **Streamable HTTP**, **WebSocket**, **HTTP/SSE**. --- ## Quick start ### 1) Install ```bash # npm npm install -g mcp-reticle # pip pip install mcp-reticle # Homebrew brew install labterminal/mcp-reticle/mcp-reticle ``` ### 2) Wrap your MCP server (stdio) Replace your MCP server command with `mcp-reticle run --name <name> -- <command...>`. Example (Claude Desktop-style config): ```json { "mcpServers": { "filesystem": { "command": "mcp-reticle", "args": ["run", "--name", "filesystem", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/work"] } } } ``` ### 3) Launch the UI ```bash mcp-reticle ui ``` ### Optional: log-only mode (no UI) ```bash mcp-reticle run --log -- npx -y @modelcontextprotocol/server-memory ``` ### Optional: proxy an HTTP-based MCP server ```bash mcp-reticle proxy --name api --upstream http://localhost:8080 --listen 3001 ``` --- ## Installation If you prefer building from source: ```bash git clone https://github.com/labterminal/mcp-reticle.git cd mcp-reticle just build ``` --- ## Documentation All guides and deep dives are in the [GitHub Wiki](https://github.com/labterminal/mcp-reticle/wiki): - [Getting started](https://github.com/labterminal/mcp-reticle/wiki/Getting-Started) - [CLI reference](https://github.com/labterminal/mcp-reticle/wiki/CLI) - [Client configuration](https://github.com/labterminal/mcp-reticle/wiki/Client-Configuration) - [Troubleshooting](https://github.com/labterminal/mcp-reticle/wiki/Troubleshooting) - [Architecture](https://github.com/labterminal/mcp-reticle/wiki/Architecture) - [Security & privacy](https://github.com/labterminal/mcp-reticle/wiki/Security) - [Development](https://github.com/labterminal/mcp-reticle/wiki/Development) - [Exports](https://github.com/labterminal/mcp-reticle/wiki/Exports) --- ## CLI overview | Command | Purpose | |---|---| | `mcp-reticle run` | Wrap stdio MCP servers and inspect traffic | | `mcp-reticle proxy` | Reverse proxy HTTP/SSE/WebSocket transports | | `mcp-reticle ui` | Launch the desktop UI | | `mcp-reticle daemon` | Headless telemetry hub | Full details: [CLI reference](https://github.com/labterminal/mcp-reticle/wiki/CLI) --- ## Security & privacy Reticle can capture tool inputs/outputs and server stderr. Treat recordings and exports as **sensitive** artifacts. Recommended reading: [Security & privacy](https://github.com/labterminal/mcp-reticle/wiki/Security) --- ## Contributing - Repo guidelines: `CONTRIBUTING.md` - Dev setup and commands: [Development guide](https://github.com/labterminal/mcp-reticle/wiki/Development) --- ## License MIT — see `LICENSE`.