<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`.
