🔍 mcp-radar

A diagnostic & testing CLI toolkit for MCP servers — scan, test, and benchmark any MCP server in one command.

中文文档

---

✨ Features

• 🔗 Auto-detect transport — stdio, SSE, or Streamable HTTP
• 📡 Scan — discover all tools, resources, and prompts with health diagnostics
• 🧪 Test — auto-test every component with smart argument generation
• ⚡ Benchmark — measure latency (P50/P90/P99), throughput, and error rates
• 📊 Reports — export to HTML, JSON, or Markdown
• 🐍 Pure Python — no Node.js required, pip install and go

🚀 Quick Start

# Install
pip install mcp-radar

# Scan an MCP server (stdio)
mcp-radar scan "uvx mcp-server-fetch"

# Scan a remote server (SSE/HTTP)
mcp-radar scan "https://my-server.com/mcp"

# Auto-test all tools
mcp-radar test "uvx mcp-server-fetch"

# Benchmark performance
mcp-radar bench "uvx mcp-server-fetch" -n 20 -c 5

# Launch interactive TUI dashboard (requires: pip install mcp-radar[tui])
mcp-radar tui "uvx mcp-server-fetch"

📦 Installation

# Basic install (CLI only)
pip install mcp-radar

# With interactive TUI dashboard
pip install mcp-radar[tui]

# With development tools
pip install mcp-radar[dev]

Requirements: Python 3.10+

📖 Usage

Scan — Discover & Diagnose

# Basic scan
mcp-radar scan "uvx some-mcp-server"

# Export report
mcp-radar scan "uvx some-mcp-server" --report html -o report.html

What it does:

• Connects to the server and retrieves capabilities
• Lists all tools, resources, and prompts
• Shows input schemas for each tool
• Runs health checks and reports issues (missing descriptions, invalid schemas, etc.)

Test — Automated Functional Testing

# Test all components
mcp-radar test "uvx some-mcp-server"

# Custom timeout per tool
mcp-radar test "uvx some-mcp-server" --tool-timeout 60

# Export results
mcp-radar test "uvx some-mcp-server" --report json -o results.json

What it does:

• Automatically calls every tool with smart-generated test arguments
• Reads every resource
• Retrieves every prompt
• Reports ✅ pass / ❌ fail / 💥 error for each component

Bench — Performance Benchmarking

# Benchmark all tools (10 iterations, sequential)
mcp-radar bench "uvx some-mcp-server"

# Heavy load test (50 iterations, 10 concurrent)
mcp-radar bench "uvx some-mcp-server" -n 50 -c 10

# Benchmark specific tools
mcp-radar bench "uvx some-mcp-server" --tools fetch --tools search

Output includes:

• Min / Mean / Median / P90 / P95 / P99 / Max latency
• Throughput (requests per second)
• Error count and error rate

Report Formats

Format	Flag	Best For
JSON	--report json	CI/CD pipelines, programmatic analysis
HTML	--report html	Sharing with team, visual reports
Markdown	--report md	GitHub issues, documentation

🏗️ How It Works

┌──────────────────────────────────────────┐
│              mcp-radar CLI               │
│                                          │
│  scan ─── scanner.py ──┐                 │
│  test ─── tester.py ───┤                 │
│  bench ── benchmarker ──┤  ──► reporter  │
│                         │     (HTML/JSON/ │
│  ┌─── client.py ───┐   │      Markdown)  │
│  │ Auto-detect      │   │                 │
│  │ transport:       │   │                 │
│  │  • stdio         │   │                 │
│  │  • SSE           │   │                 │
│  │  • HTTP          │   │                 │
│  └──────────────────┘   │                 │
└──────────────────────────────────────────┘

⚙️ Configuration

Transport Auto-Detection

Server Argument	Detected Transport
uvx some-server	stdio
python -m my_server	stdio
http://localhost:8080/sse	SSE
https://api.example.com/mcp	Streamable HTTP

Global Options

Flag	Description
-v, --verbose	Enable debug logging
-t, --timeout	Connection timeout (default: 30s)
--report	Export format: json, html, md
-o, --output	Report output file path

🛠️ Development

# Clone
git clone https://github.com/junjunup/mcp-radar.git
cd mcp-radar

# Install with dev deps
make dev

# Run tests
make test

# Run tests with coverage
make coverage

# Lint
make lint

# Format
make format

# Full audit (lint + typecheck + security + coverage)
make audit

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Make your changes with tests
4. Ensure make audit passes
5. Submit a pull request

📄 License

MIT — use it however you like.

🔗 Related Projects

• MCP SDK — Official Python SDK for MCP
• FastMCP — Fast, Pythonic way to build MCP servers
• MCP Inspector — Official MCP debugging tool (Web UI)