Mcp Doctor

MCP Doctor 🩺

A comprehensive diagnostic tool for MCP (Model Context Protocol) servers

[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://github.com/psf/black) [](https://github.com/destilabs/mcp-doctor/actions) [](https://codecov.io/gh/destilabs/mcp-doctor) [](https://coveralls.io/github/destilabs/mcp-doctor?branch=main) [](https://github.com/destilabs/mcp-doctor/stargazers) [](https://github.com/destilabs/mcp-doctor/issues)

MCP Doctor is your go-to diagnostic tool for analyzing MCP servers and ensuring they follow best practices for AI agent integration. Just like a medical doctor diagnoses health issues, MCP Doctor diagnoses your MCP servers to ensure they're agent-friendly, performant, and compliant with Anthropic's best practices.

🎯 What is MCP Doctor?

MCP Doctor performs comprehensive health checks on your MCP servers, whether they're running as traditional HTTP services or launched via NPX commands. It analyzes tool descriptions, parameter schemas, and server behavior to provide actionable recommendations for improving AI agent compatibility.

✨ Key Features

• 🔍 Deep Analysis - Comprehensive evaluation of MCP server health
• 🌐 Universal Support - Works with HTTP servers and NPX-launched packages
• 🔧 Environment Handling - Secure API key and environment variable management
• 📊 Rich Reports - Beautiful terminal output with detailed diagnostics
• 🔒 Security Audit - Detects authentication gaps, exposed credentials, and insecure configurations
• 🚀 Easy Integration - Simple CLI and Python API
• ⚡ Fast Execution - Async operations for quick analysis

🧠 Philosophy

MCP Doctor is built around two core principles that drive every design decision:

⚡ Speed First

This tool is designed for frequent, everyday usage by developers and AI engineers. Speed is paramount:

• No AI dependencies - We deliberately avoid LLM-based evaluation to ensure consistent, fast analysis
• Rule-based analysis - Lightning-fast pattern matching and heuristic evaluation
• Async architecture - Concurrent operations for maximum performance
• Minimal overhead - Direct protocol communication without unnecessary abstractions

Why this matters: When you're iterating on MCP servers, waiting 30+ seconds for AI-powered analysis breaks your flow. MCP Doctor gives you actionable insights in seconds, not minutes.

🔒 Security Paramount

Security isn't an afterthought—it's baked into every feature:

• Smart credential filtering - Automatically detects and hides sensitive environment variables from logs
• Configurable privacy levels - From secure filtering to complete logging disablement
• No data transmission - All analysis happens locally; your secrets never leave your machine
• Secure defaults - Safe configurations out of the box

Why this matters: MCP servers often handle sensitive API keys, database credentials, and private data. MCP Doctor ensures your secrets stay secret while providing the insights you need.

These principles ensure MCP Doctor remains a tool you'll reach for daily—fast enough for rapid iteration, secure enough for production environments.

🚀 Quick Start

Basic Usage

# Diagnose an HTTP MCP server
mcp-doctor analyze --target http://localhost:8000/mcp

# Diagnose an NPX-launched MCP server
mcp-doctor analyze --target "npx firecrawl-mcp"

# Diagnose with environment variables
mcp-doctor analyze --target "export FIRECRAWL_API_KEY=your_key && npx firecrawl-mcp"

# Run token efficiency analysis
mcp-doctor analyze --target "npx firecrawl-mcp" --check token_efficiency

# Run all available checks
mcp-doctor analyze --target "npx firecrawl-mcp" --check all

# Run the security audit
mcp-doctor analyze --target http://localhost:8000/mcp --check security

# Inspect an NPX-launched server for risky tools
mcp-doctor analyze --target "npx firecrawl-mcp" --check security

# Get detailed diagnostic output
mcp-doctor analyze --target http://localhost:8000/mcp --verbose

🎬 Demonstrations

NPX Server Analysis

See MCP Doctor in action analyzing an NPX-launched MCP server:

[📹 Watch NPX Analysis Demo](./docs/video/MCP%20doctor%20_%20npx.mp4)

HTTP Server Analysis

Watch MCP Doctor diagnose an HTTP MCP server:

[📹 Watch HTTP Analysis Demo](./docs/video/MCP-doctor%20_%20http.mp4)

🩺 Diagnostic Capabilities

📝 Tool Description Analysis

• Clarity Assessment - Evaluates description readability and completeness
• Context Validation - Ensures tools explain when and how to use them
• Parameter Naming - Checks for descriptive vs generic parameter names
• Purpose Clarity - Validates that each tool's purpose is clearly stated
• Jargon Detection - Identifies technical terms that should be simplified

🔢 Token Efficiency Analysis

• Response Size Measurement - Analyzes actual tool response token counts
• Pagination Detection - Identifies tools that need pagination support
• Filtering Capabilities - Checks for response filtering options
• Format Control - Evaluates response format customization
• Verbose Identifier Detection - Flags technical IDs that could be simplified
• Performance Metrics - Measures response times and sizes

🔮 Future Diagnostics (Roadmap)

• Schema Validation - Parameter schema compatibility checks
• Performance Analysis - Response time and resource usage evaluation
• Integration Testing - Agent interaction simulation

🌐 Server Support

HTTP Servers

mcp-doctor analyze --target http://localhost:8000/mcp
mcp-doctor analyze --target https://api.example.com/mcp

NPX Packages

# Basic NPX analysis
mcp-doctor analyze --target "npx firecrawl-mcp"

# With environment variables (inline)
mcp-doctor analyze --target "export API_KEY=abc123 && npx firecrawl-mcp"

# With environment variables (JSON format)
mcp-doctor analyze --target "npx firecrawl-mcp" --env-vars '{"API_KEY": "abc123"}'

# With custom working directory
mcp-doctor analyze --target "npx firecrawl-mcp" --working-dir "/path/to/project"

📊 Output Formats

# Beautiful table output (default)
mcp-doctor analyze --target "npx firecrawl-mcp" --output-format table

# JSON for programmatic use
mcp-doctor analyze --target "npx firecrawl-mcp" --output-format json > report.json

# YAML for human-readable structured data
mcp-doctor analyze --target "npx firecrawl-mcp" --output-format yaml

# Export an HTML snapshot (preserves Rich styling)
mcp-doctor analyze --target "npx firecrawl-mcp" --export-html ./docs/report.html

# Show raw tool outputs during token efficiency checks
mcp-doctor analyze --target "npx firecrawl-mcp" --check token_efficiency --show-tool-outputs

Note: HTML export uses Rich's export_html to preserve colors, tables, and emojis in a single standalone file.

🛠 Token Efficiency Overrides

For tools that require specific parameters during token efficiency checks, you can supply overrides via a JSON/YAML file.

Usage:

mcp-doctor analyze --target "npx firecrawl-mcp" --check token_efficiency --overrides ./overrides.json

Example overrides.json:

{
  "tools": {
    "analyse-video": { "videoId": "68d52f0c18ca9db9c9db6bb0", "type": "summary" },
    "analyze-video": { "videoId": "68d52f0c18ca9db9c9db6bb0", "type": "summary" },
    "search-docs": { "query": "sample query", "limit": 10 }
  }
}

Notes:

• Keys are matched case-insensitively; spaces/underscores are normalized (e.g., analyze_video → analyze-video).
• If the file does not contain a top-level tools key, the top-level mapping is used directly.

🔧 Python API

HTTP Server Diagnosis

import asyncio
from mcp_analyzer.mcp_client import MCPClient
from mcp_analyzer.checkers.descriptions import DescriptionChecker

async def diagnose_http_server():
    client = MCPClient("http://localhost:8000/mcp")
    
    try:
        tools = await client.get_tools()
        
        checker = DescriptionChecker()
        results = checker.analyze_tool_descriptions(tools)
        
        return results
    finally:
        await client.close()

# Run diagnosis
results = asyncio.run(diagnose_http_server())
print(f"Found {len(results['issues'])} issues")

NPX Server Diagnosis

import asyncio
from mcp_analyzer.mcp_client import MCPClient
from mcp_analyzer.checkers.descriptions import DescriptionChecker

async def diagnose_npx_server():
    # Method 1: Environment variables in command
    client = MCPClient("export FIRECRAWL_API_KEY=abc123 && npx firecrawl-mcp")
    
    # Method 2: Environment variables via kwargs
    # client = MCPClient("npx firecrawl-mcp", env_vars={"FIRECRAWL_API_KEY": "abc123"})
    
    try:
        # Server will be launched automatically
        server_info = await client.get_server_info()
        tools = await client.get_tools()
        
        checker = DescriptionChecker()
        results = checker.analyze_tool_descriptions(tools)
        
        print(f"Diagnosed NPX server at: {client.get_server_url()}")
        return results
        
    finally:
        # This will automatically stop the NPX server
        await client.close()

# Run diagnosis
results = asyncio.run(diagnose_npx_server())
print(f"Found {len(results['issues'])} issues")

🏥 Example Diagnostic Report

🩺 MCP Doctor - Server Diagnosis
NPX Command: export FIRECRAWL_API_KEY=abc123 && npx firecrawl-mcp

✅ NPX server launched at http://localhost:3001
✅ Connected! Found 12 tools

📝 Tool Description Analysis
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┓
┃ Diagnostic Result            ┃    Count ┃ Percentage ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━┩
│ ✅ Healthy Tools             │        8 │      66.7% │
│ ⚠️  Warnings                 │        3 │      25.0% │
│ 🚨 Critical Issues           │        1 │       8.3% │
│ ℹ️  Recommendations          │        5 │      41.7% │
└──────────────────────────────┴──────────┴────────────┘

🎯 Treatment Recommendations:
   1. Add descriptions to 1 tool missing documentation
   2. Improve parameter naming for 3 tools with generic names
   3. Add usage context to 2 tools for better agent understanding
   4. Simplify technical jargon in 2 tool descriptions

Token Efficiency Analysis Example

🩺 MCP Doctor - Server Diagnosis
NPX Command: npx firecrawl-mcp

✅ NPX server launched at http://localhost:3001
✅ Connected! Found 8 tools

🔢 Token Efficiency Analysis
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Metric                       ┃ Value         ┃ Status                    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Average Response Size        │ 3,250 tokens  │ ✅ Efficient             │
│ Largest Response             │ 28,500 tokens │ 🚨 Oversized             │
│ Tools Over 25k Tokens        │ 1             │ 🚨 1                     │
│ Tools Successfully Analyzed  │ 8/8           │ ✅ Complete              │
└──────────────────────────────┴───────────────┴───────────────────────────┘

🚨 Token Efficiency Issues Found:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tool                         ┃ Severity ┃ Issue                                                                        ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ scrape_url                   │ ⚠️       │ Response contains 28,500 tokens (>25,000 recommended)                       │
│ scrape_url                   │ ℹ️       │ Tool would benefit from filtering capabilities to reduce response size       │
│ list_crawl_jobs              │ ℹ️       │ Tool likely returns collections but doesn't support pagination              │
│ get_crawl_status             │ ℹ️       │ Responses contain verbose technical identifiers (UUIDs, hashes)             │
└──────────────────────────────┴──────────┴──────────────────────────────────────────────────────────────────────────┘

🎯 Token Efficiency Recommendations:
   1. Implement response size limits for 1 tool with oversized responses (>25k tokens)
   2. Add pagination support to 1 tool that returns collections
   3. Add filtering capabilities to 1 tool to reduce response size
   4. Replace verbose technical identifiers with semantic ones in 1 tool

📋 CLI Reference

analyze Command

Main diagnostic command for MCP servers.

mcp-doctor analyze [OPTIONS]

Options:

• --target TEXT (required): MCP server URL or NPX command to diagnose
• --check {descriptions,token_efficiency,all}: Type of diagnosis to run (default: descriptions)
• --output-format {table,json,yaml}: Output format (default: table)
• --verbose / --no-verbose: Show detailed diagnostic output (default: False)
• --timeout INTEGER: Request timeout in seconds (default: 30)
• --env-vars TEXT: Environment variables for NPX command (JSON format)
• --working-dir TEXT: Working directory for NPX command
• --env-file PATH: Optional .env file loaded before running the command

generate-dataset Command

Create synthetic datasets of MCP tool use cases using Claude or GPT models.

# Generate 8 tasks using tools fetched from a running server
export ANTHROPIC_API_KEY=sk-ant-example
mcp-doctor generate-dataset --target http://localhost:8000/mcp --num-tasks 8 --llm-timeout 90 --output dataset.json

# Generate 8 tasks using tools from an NPX command
export OPENAI_API_KEY=sk-open-example
mcp-doctor generate-dataset --target "npx firecrawl-mcp" --num-tasks 8 --output dataset.json

# Generate tasks from a local JSON definition using OpenAI
export OPENAI_API_KEY=sk-open-example
mcp-doctor generate-dataset --tools-file tools.json --num-tasks 5

# Generate tasks and upload them to LangSmith
export LANGSMITH_API_KEY=ls-example
mcp-doctor generate-dataset --target http://localhost:8000/mcp --num-tasks 5 \
  --push-to-langsmith --langsmith-project "MCP Evaluation" \
  --langsmith-dataset-name "MCP Doctor Synthetic"

Set either ANTHROPIC_API_KEY (Claude 4 Sonnet) or OPENAI_API_KEY (GPT-4.1) before running the command. The output is a JSON array containing prompt, tools_called, tools_args, retrieved_contexts, response, and reference entries ready for downstream evaluations. Use --llm-timeout to extend the wait for slower model responses when needed (defaults to 60 seconds).

Add --push-to-langsmith to stream the generated data straight into your LangSmith workspace. Provide a key via --langsmith-api-key or the LANGSMITH_API_KEY environment variable and optionally customize the dataset name (--langsmith-dataset-name), project tag (--langsmith-project), description (--langsmith-description), and API endpoint (--langsmith-endpoint). Use --env-file path/to/.env when you prefer file-based secrets over inline JSON.

version Command

Show version and diagnostic capabilities.

mcp-doctor version

🏗️ Development

Project Structure

mcp-doctor/
├── src/mcp_analyzer/       # Main package
│   ├── cli.py              # CLI interface
│   ├── mcp_client.py       # MCP server communication
│   ├── mcp_stdio_client.py # STDIO transport client
│   ├── npx_launcher.py     # NPX server management
│   ├── reports.py          # Output formatting
│   └── checkers/           # Diagnostic modules
│       └── descriptions.py # Description analysis
└── tests/                  # Test suite

Development Setup

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage (using pytest-cov)
pytest --cov=src/mcp_analyzer --cov-report=html --cov-report=term

# Or use coverage directly
coverage run -m pytest
coverage report -m

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [destilabs](https://github.com/destilabs)
- **Source:** [destilabs/mcp-doctor](https://github.com/destilabs/mcp-doctor)
- **License:** MIT
- **Homepage:** https://www.destilabs.com/

Install and usage instructions live in the source repository linked above.