# MCP Doctor [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Jiansen/mcp-doctor  
**GitHub Stars:** 1  
**npm Downloads (last month):** 74  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-doctor

## Description
Check and improve the contract quality of any MCP server — for humans, agents, and platforms.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "mcp-doctor": {
    "command": "uvx",
    "args": ["mcp-doctor"],
    "env": {
      "OPENAI_API_KEY": "",
      "OPENAI_BASE_URL": "",
      "MCP_DOCTOR_MODEL": ""
    }
  }
}
```

**Requires environment variables:** `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `MCP_DOCTOR_MODEL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```bash
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:

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

_Full upstream README: https://allmcps.com/mcp/mcp-doctor/readme_