MCP Doctor
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.
Related MCP server: checkyourself
Quick Start
pip install mcp-doctor
mcp-doctor check /path/to/your-mcp-serverWhat 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
# 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-4oAs 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. Usemode="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 commandpython -m mcp_doctor.mcp_server. Then use thecheck_servertool to check any MCP server's quality.
Step by step:
Install:
pip install mcp-doctorAdd to your MCP configuration:
{ "mcpServers": { "mcp-doctor": { "command": "python", "args": ["-m", "mcp_doctor.mcp_server"] } } }Use the
check_servertool with a path to any MCP server repoIf 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) |
| Yes | No | No |
AI-enhanced |
| No | Yes (LLM API) |
|
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 |
| Parse MCP metadata |
| Check documentation quality |
| Verify license presence |
| 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
ghCLI):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/ -vIf MCP Doctor helped you improve your server, consider giving it a star on GitHub — it helps others discover the tool.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Free MCP contract auditing for AI agents and developers. Check tool schemas, detect potential breaking changes between versions, and get structured compatibility findings before deployment. Static analysis only.
The OpenZeppelin Solidity Contracts MCP server integrates OpenZeppelin's security and style rules into AI-driven development workflows, enabling AI assistants to generate safe, correct, and production-ready smart contracts. It automatically validates generated code against OpenZeppelin standards (including imports, modifiers, naming conventions, and security checks) and supports various contract types including ERC-20, ERC-721, ERC-1155, Stablecoins, RWA, Governor, and Account contracts through prompt-driven workflows.
Audit your MCP servers for poisoned tools and leaked secrets, and check AI-generated code for flaws.
Search, vet & assemble MCP servers from your agent: verified tools, risk labels, and trust scores.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enhances AI-generated code quality through comprehensive analysis across 10 critical dimensions, helping identify issues before they become problems.190Apache 2.0
- AlicenseAqualityBmaintenanceLocal-first production-readiness MCP server for AI-built apps. It runs read-only checks, produces an evidence-based readiness score, and guides fixes before launch.1125 npm7Apache 2.0
- AlicenseAqualityDmaintenanceAn MCP server that gives autonomous coding agents deterministic, schema-validated tools for EVM smart contract development — security scanning, gas profiling, compiler diagnostics, and transaction simulation.91MIT
- AlicenseAqualityDmaintenanceMCP server for measuring, tracking, scoring, and improving AI agent reliability with tools for recording interactions, scoring reliability, analyzing failures, recommending improvements, generating audit reports, and checking MCP health.8MIT