Content
<!-- mcp-name: io.github.Jiansen/mcp-doctor -->
<p align="center">
<img src="assets/avatar-512.png" width="120" alt="mcp-doctor logo">
</p>
<h1 align="center">MCP Doctor</h1>
<p align="center">
<a href="https://pypi.org/project/mcp-doctor/"><img src="https://img.shields.io/pypi/v/mcp-doctor" alt="PyPI"></a>
<a href="https://github.com/Jiansen/mcp-doctor/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
<a href="https://pypi.org/project/mcp-doctor/"><img src="https://img.shields.io/pypi/pyversions/mcp-doctor" alt="Python"></a>
<a href="https://github.com/Jiansen/mcp-doctor/stargazers"><img src="https://img.shields.io/github/stars/Jiansen/mcp-doctor?style=social" alt="GitHub Stars"></a>
</p>
<p align="center">Check and improve the contract quality of any MCP server — for humans, agents, and platforms.</p>
## 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
```bash
pip install mcp-doctor
mcp-doctor check /path/to/your-mcp-server
```
## What It Checks
| Dimension | Question |
|-----------|----------|
| **Task Clarity** | Is the server's purpose immediately clear? |
| **Trust & Safety** | Are side effects, permissions, and safety boundaries declared? |
| **Interface Quality** | Are tools well-named, well-described, and well-typed? |
| **Token Efficiency** | Will tool responses fit an agent's context budget? |
| **Install Friction** | How fast can someone go from discovery to first use? |
| **Cross-platform Readiness** | Is metadata complete for Registry, Smithery, PulseMCP, Glama? |
## Usage
### CLI
```bash
# 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:
```json
{
"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
| Mode | Flag | Deterministic | Network | API Key |
|------|------|:---:|:---:|:---:|
| **Rule-based** (default) | `--mode rule` | Yes | No | No |
| **AI-enhanced** | `--mode ai` | No | Yes (LLM API) | `OPENAI_API_KEY` |
**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.
| What it accesses | Why |
|-----------------|-----|
| `server.json` | Parse MCP metadata |
| `README.md` | Check documentation quality |
| `LICENSE` | Verify license presence |
| `*.py`, `*.json` in `src/` | Detect tool definitions |
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
```bash
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.
[](https://github.com/Jiansen/mcp-doctor)
## License
MIT
