MCP Doctor

What MCP Doctor MCP server does

MCP Doctor MCP server reviews the contract an MCP server presents to platforms, developers, and AI agents. It examines six dimensions:

• Task clarity: whether the server’s purpose is easy to understand
• Trust and safety: whether permissions, side effects, and safety boundaries are declared
• Interface quality: whether tools are named, described, and typed clearly
• Token efficiency: whether responses are likely to fit an agent’s context budget
• Install friction: how quickly a user can move from discovery to first use
• Cross-platform readiness: whether metadata is prepared for the MCP Registry, Smithery, PulseMCP, and Glama

Each dimension receives a score from 0 to 100 and a grade from A to D. Reports include recommendations that help identify which areas need attention first. This makes the MCP Doctor MCP server relevant to the 💻 Developer Tools category, particularly for maintainers assessing documentation and tool definitions before publishing.

How it works

Install the package with pip install mcp-doctor, then run a check against an MCP server repository:

mcp-doctor check /path/to/server

The default rule-based mode is deterministic and works offline. It does not require network access, an LLM, or an API key. Results can be emitted as terminal output, JSON for CI/CD workflows, or Markdown for reports and README content:

mcp-doctor check /path/to/server --format json
mcp-doctor check /path/to/server --format markdown

MCP Doctor MCP server can also be added to an MCP client using the python -m mcp_doctor.mcp_server command. Its check_server tool accepts a target path, output format, evaluation mode, and model; list_dimensions reports the areas it evaluates.

The optional AI mode uses --mode ai and can accept a model with --model. It sends a metadata summary containing the server name, tool definitions, a README preview, and rule-based scores to an OpenAI-compatible API. Source code is not sent. Install the optional dependency with pip install mcp-doctor[ai].

Setup and configuration

The basic setup requires Python package installation and a path to the MCP server being reviewed. To configure the MCP interface, add an entry with command python and arguments -m mcp_doctor.mcp_server to the client’s MCP configuration.

AI mode requires OPENAI_API_KEY. OPENAI_BASE_URL can point to a custom OpenAI-compatible endpoint, including Ollama, vLLM, LM Studio, or Azure. MCP_DOCTOR_MODEL selects the model and defaults to gpt-4o-mini when not otherwise specified.

Tools and capabilities

The MCP Doctor MCP server provides two documented tools:

• check_server(path, format, mode, model): runs all six checks, with mode="ai" available for LLM-enhanced review
• list_dimensions(): lists the evaluation dimensions

The checker reads server.json, README.md, LICENSE, and Python or JSON files under src/ when inspecting a target. It is read-only: it does not create, modify, or delete files. Its MCP tools are annotated with readOnlyHint: true and destructiveHint: false.

Limitations and notes

AI evaluation is not deterministic and requires network access plus an API key. Rule-based evaluation is the option to use when repeatable, offline results are needed. The tool evaluates the target server’s contract and metadata; the provided material does not describe it as a runtime test suite or an implementation verifier.

A practical workflow is to check a server, review its scores, locate the lowest-scoring dimensions, and apply the recommendations. If MCP access is unavailable, the CLI can produce JSON for an agent or automation workflow.