● Free & open source · MIT · Zero dependencies

Point it at any MCP server.
It tells you what's broken.

Building an MCP server is easy. Knowing whether it actually works, won't confuse the model, and isn't a security hole is the hard part. mcp-doctor launches your server, runs the full handshake, introspects everything it exposes, and reports problems — with a real exit code for CI.

Get started ★ Star on GitHub

One command · pipx install mcp-doctor · works with Python & Node servers over stdio

bash — mcp-doctor

$ mcp-doctor -- python -m my_server

  mcp-doctor  ->  my-server 0.1.0
  protocol 2024-11-05  |  27 tools, 3 resources, 0 prompts

  ERROR  [prompt-injection] A tool description contains override-style language…
  ERROR  [missing-description] Tool 'helper' has no description…
  WARN   [tool-bloat] 27 tools exposed. Selection accuracy degrades past ~20…
  WARN   [dangerous-tool] Tool 'run_shell' looks like it executes commands…

  FAIL  2 error(s), 2 warning(s).

// what it checks

Three questions about every MCP server

Every check maps to a real, reported failure mode when running MCP servers with Claude and other agents — not hypotheticals.

HEALTH

Does it even run?

Server starts & completes the initialize handshake
Catches the classic "it just outputs nothing"
Enumerates tools, resources & prompts — the real surface

QUALITY

Will the model use it well?

Tool bloat — flags when you expose so many tools selection accuracy drops
Missing, thin, oversized or duplicate descriptions
Missing or weak input schemas

SECURITY

Is it a foot-gun?

Prompt injection — override-style language hidden in descriptions
Dangerous surface — tools/params that look like they shell out or eval
Secret leakage — API keys or private keys in server metadata

// quickstart

Two lines to a verdict

Everything after -- is how you launch your server over stdio. It's run as an argument list, never through a shell.

Install

pipx install mcp-doctor

Or pip install mcp-doctor. Zero runtime dependencies — nothing to break your environment.

Point & run

mcp-doctor -- python -m my_server

Works with any stdio server — node build/index.js, a binary, whatever launches it.

Read the exit code

echo $?

0 when clean, 1 on an error-level finding. Add --json for machine-readable output.

// continuous integration

Drops straight into your pipeline

The official Inspector is a GUI — great for poking around, useless in CI. mcp-doctor is the command-line counterpart that fails your build when the server regresses.

.github/workflows/mcp.yml

- run: pipx install mcp-doctor
- run: mcp-doctor -- python -m my_server   # exits 1 on an error-level issue

// no paywall, ever

mcp-doctor is free — and staying that way

No pro tier, no locked checks, no "contact sales." If it caught a prompt-injection string, saved you a broken CI run, or just taught you something about your own server — you can say thanks. Every donation goes straight into keeping this and the rest of the toolkit maintained and free.

$ mcp-doctor --cost → 0.00 (always)

♥ Sponsor on GitHub & keep it free

One-time or monthly, whatever feels fair — straight from your GitHub account. Cancel anytime.

Prefer crypto? BEP20 (BSC): 0x2aed4e50cf319ad63575c54b1db8040fe90653a9 BNB Smart Chain network only.

⭐ Star the repo — free, helps more

🐛 Open an issue — tell me what broke

📣 Share it — with one dev who ships MCP servers

// part of a small family

Dependency-light tools for people who build with agents

mcp-doctor

Health, lint & security audit for MCP servers. You're here.