io.github.Jiansen/mcp-doctor

Problem

Most MCP servers are built with only one audience in mind (usually human developers reading a README). But a successful MCP server needs to satisfy three audiences simultaneously:

• Distribution platforms (Registry, Smithery, PulseMCP, Glama) need structured metadata
• Human users need clear purpose, trust signals, and low install friction
• AI agents need unambiguous tool descriptions, declared side effects, and token-efficient responses

MCP Doctor checks all six dimensions of "contract quality" and gives you actionable recommendations.

Quick Start

pip install mcp-doctor
mcp-doctor check /path/to/your-mcp-server

What It Checks

Usage

CLI

# Terminal output (default, rule-based)
mcp-doctor check /path/to/server

# JSON output (for CI/CD)
mcp-doctor check /path/to/server --format json

# Markdown output (for README badges or reports)
mcp-doctor check /path/to/server --format markdown

# AI-enhanced evaluation (requires OPENAI_API_KEY)
mcp-doctor check /path/to/server --mode ai

# AI mode with a specific model
mcp-doctor check /path/to/server --mode ai --model gpt-4o

As an MCP Server

MCP Doctor is also an MCP server, so AI agents can use it to check other servers:

{
  "mcpServers": {
    "mcp-doctor": {
      "command": "python",
      "args": ["-m", "mcp_doctor.mcp_server"]
    }
  }
}

Tools:

• check_server(path, format, mode, model) — Run all 6 checks. Use mode="ai" for LLM-enhanced review.
• list_dimensions() — List what MCP Doctor evaluates

For AI Agents: Quick Install

One-liner (paste this to your AI agent):

Install mcp-doctor (pip install mcp-doctor) and add it to your MCP config with command python -m mcp_doctor.mcp_server. Then use the check_server tool to check any MCP server's quality.

Step by step:

1. Install: pip install mcp-doctor
2. Add to your MCP configuration:
   json

   {
     "mcpServers": {
       "mcp-doctor": {
         "command": "python",
         "args": ["-m", "mcp_doctor.mcp_server"]
       }
     }
   }
   

3. Use the check_server tool with a path to any MCP server repo
4. If MCP is not available, fall back to CLI: mcp-doctor check /path/to/server --format json

Agent workflow: check server -> review scores -> identify lowest dimensions -> follow recommendations

Scoring

Each dimension is scored 0-100 and graded A/B/C/D:

• A (90+): Exemplary
• B (75-89): Good, minor gaps
• C (55-74): Adequate, notable gaps
• D (<55): Needs significant improvement

Theoretical Foundation

MCP Doctor is based on the Contract Quality Framework — the principle that a successful MCP product's promises (what it does, what it costs, what risks it carries) should be equally parseable by platforms, humans, and agents.

The framework draws from:

• Anthropic's "Writing effective tools for agents" (tool description engineering, namespacing, token efficiency)
• Official MCP Registry requirements (server.json schema, namespace verification)
• Cross-platform analysis of Smithery, PulseMCP, Glama ranking signals

Evaluation Modes

Rule-based mode is fully offline and deterministic. No network calls, no LLM, no API keys needed.

AI mode sends a metadata summary (server name, tool definitions, README preview, rule-based scores) to an OpenAI-compatible API for qualitative review. No source code is sent. Reports include model name and version for reproducibility.

AI mode supports any OpenAI-compatible provider:

• OPENAI_API_KEY — API key (required for AI mode)
• OPENAI_BASE_URL — Custom endpoint (for Ollama, vLLM, LM Studio, Azure, etc.)
• MCP_DOCTOR_MODEL — Model name (default: gpt-4o-mini)

Install AI support: pip install mcp-doctor[ai]

Trust & Permissions

MCP Doctor is read-only. It never modifies, deletes, or creates files.

All MCP tools have readOnlyHint: true and destructiveHint: false annotations.

Feedback

Found a bug? Have a suggestion? We'd love to hear from you:

• GitHub Issues: https://github.com/Jiansen/mcp-doctor/issues
• Quick report (if you have gh CLI):
  bash

  gh issue create --repo Jiansen/mcp-doctor --title "Bug: ..." --body "..."
  

If you're an agent, include the JSON output of check_server in your report for context.

Contributing

git clone https://github.com/Jiansen/mcp-doctor.git
cd mcp-doctor
pip install -e ".[dev,ai]"
ruff check src/ tests/
pytest tests/ -v

If MCP Doctor helped you improve your server, consider giving it a star on GitHub — it helps others discover the tool.

License

MIT