mcp-doctor

Evals and guardrails for AI agents and the MCP tools they call. Lint, fuzz and guard a server to catch what breaks the agent: in the code, before release, and on every live call.

An agent is only as reliable as the tools it calls, and most MCP servers ship unchecked: tools with no description, parameters the model has to guess, errors that crash the session, a "success" that never happened, a prompt injection that walks a secret out the door. mcp-doctor checks a server at every stage, from the first line of code to the live agent call. Python, TypeScript, Go and Rust; runs in CI, Claude Code, Codex and Cursor.

| When | Command | What it answers | |---|---|---| | Writing it | mcp-doctor . · --fix · --diff-against | Can an agent understand and safely call these tools? What changed since the last release? | | Every PR | GitHub Action · pre-commit | The same, on the lines that changed, with one-click fixes. Add run: for a verdict. | | Before release | fuzz · fuzz --truth · verdict | Does it fail cleanly on bad input? Is a "success" a real answer? Ship it? | | In production | guard · guard hook · mcp_doctor.session | Did that call actually work? Is a secret about to leave after a prompt injection? | | Anywhere | browser · issue bot · plugin for Claude Code, Codex, Cursor | The same checks with nothing to install, or from inside your editor. |

<p align="center"><img src="docs/demo.svg" width="940" alt="Animated demo: mcp-doctor lints a server (1 finding that will break an agent, quality 22%, grade F), gives a release verdict (BLOCK, then SHIP), and guards a live call that reported success without writing the file"></p>

Real output from mcp-doctor 0.35.0 on the bundled example servers and guard's test fixture, long lines cut and some findings left out (how it's built).

In use: jupyter-mcp-server (1.3K★) runs the Action on every PR, added after its maintainer asked for it. Fixes from mcp-doctor's findings have been merged upstream in telegram-mcp (111 tools in one PR), davinci-resolve-mcp (shipped as its own release) and ha-mcp (5.1K★); 61 merged upstream fixes in 58 repos.

Contents: Try it · Why trust it · Scan and fix · GitHub Action · pre-commit · Fuzz and verdict · Guard · Plugin · What it checks · Security checks · Install · Limitations · Roadmap

Try it in 30 seconds

• In your browser: check any MCP server. Paste a GitHub repo, npm or PyPI name and get both grades in seconds. The real mcp-doctor runs in your browser (Pyodide); nothing is uploaded or run.
• No install, as a GitHub issue: open a scan request with your server's GitHub URL. A bot replies with the report in a few minutes. It reads the code only and never runs it. Security findings are posted as counts only, since the issue is public.
• CLI: pip install mcp-server-lint, then mcp-doctor path/to/your/server
• Fuzz a running server: uvx --from 'mcp-server-lint[runtime]' mcp-doctor fuzz -- python server.py, or mcp-doctor verdict . --run "python server.py" for one SHIP / FIX-FIRST / BLOCK decision (details)
• Running an agent? Put mcp-doctor guard in front of any MCP server, and the agent is told when a tool says "success" but the write didn't land, its arguments were ignored, or it didn't do what it claims
• Claude Code, Codex or Cursor: install the plugin (Claude Code: /plugin install mcp-doctor --marketplace vishalhabib99/mcp-doctor; Codex: codex plugin marketplace add vishalhabib99/mcp-doctor), then ask "check my MCP server". The agent scans, explains each finding, and fixes what it can with your OK (details)
• CI: uses: vishalhabib99/mcp-doctor@v1 comments on each PR, suggests one-click fixes on the lines it changes, and can fail a PR that drops below your score (details)

<a id="why-trust-the-grade"></a>

Why trust its findings

• Recall is measured, misses are published. A checker that can't see a tool quietly grades it as fine, so tool detection is measured against an independent count: 15,755 of 15,977 tools found across 805 real servers on 5 frameworks. Every miss is listed with its reason in docs/coverage.md.
• Breakages first, grades second. Every report opens with what will break an agent calling the server, from checks maintainers have already acted on: an optional argument that rejects the null its own schema advertises (fixed by maintainers in 20 repos), stray stdout on a stdio server (3 repos), a server that won't start on a fresh install of mcp 2.x. Before the fix, 17 of the 19 such bugs maintainers merged showed up this way, while the grade gave most of those repos an A. On 20 repos it had never seen, the lines checked by hand were 96% right (53 of 55 read in full, plus 16 of 16 sampled from two repos with hundreds). The grades still follow, for everything else.
• 131 of its own bugs found and fixed after release by running it on real servers, up to the 91.5k★ official modelcontextprotocol/servers monorepo; a fix ships only when a before/after run on 120+ real repos changes nothing it shouldn't. The log · how 69 of them got through.
• Maintainers act on its reports: fixes merged upstream, among them ha-mcp, telegram-mcp (111 tools fixed in one PR) and davinci-resolve-mcp (shipped as its own release).
• Quality and security are graded separately, so a well-documented A can't hide a security gap. Every audited repo is on the leaderboard with a dated badge you can add to your README, and re-scans show ▲/▼ drift.
• What the first outside users hit, and what changed because of it: docs/what-users-taught-me.md.

<a id="lint-and-fix"></a>

Scan the code and fix it in place

The static scan reads source and never runs it. Point it at a server and it leads with what will break an agent, then two grades and every finding:

$ mcp-doctor .
mcp-doctor report
Will break an agent: 3
  search(limit) (server.py:5): a client that sends the advertised null default gets a validation error, and the tool never runs.
      Fix: type it `T | None` (`mcp-doctor --fix` does this). (fixed by maintainers in 20 repos)
  search (server.py:12): stray stdout on stdio corrupts the JSON-RPC stream: calls time out (Python) or the client logs parse errors (Node).
      Fix: write to stderr or use logging. (fixed by maintainers in 3 repos)
  server.py:1: a fresh install gets mcp 2.x and the server fails to start.
      Fix: pin `mcp<2`, or migrate the removed import. (removed in mcp 2.x; fails on import)

Quality:  34%  Grade: F  (1 tool(s) found)

When none are found it says so, and names what it looked for: No known agent-breaking issues (checked: null defaults, stdout on stdio, mcp 2.x start-up). --json lists them under breakages, with breakage_count.

A live scan of homeassistant-ai/ha-mcp (5.1k★). The bundled examples, before and after:

$ mcp-doctor examples/bad_server
mcp-doctor report
Will break an agent: 1
  run(timeout) (server.py:18): a client that sends the advertised null default gets a validation error, and the tool never runs.
      Fix: type it `T | None` (`mcp-doctor --fix` does this). (fixed by maintainers in 20 repos)

Quality:  22%  Grade: F  (2 tool(s) found)
Security: 100%  Grade: A

  [FAIL] do_thing (server.py:12)
      ERROR  Tool has no description. An agent cannot decide when to call this.
      WARNING  2/2 parameters have no type annotation.
      WARNING  Parameters aren't documented — no Args:/:param: docstring section and no per-parameter Field(description=...) — the model only sees …
      WARNING  No try/except in this function's own body. FastMCP still catches an unhandled exception here and returns a structured error rather …
  [FAIL] run (server.py:18)
      ERROR  Tool has no description. An agent cannot decide when to call this.
      WARNING  1/2 parameters have no type annotation.
      WARNING  Parameters aren't documented — no Args:/:param: docstring section and no per-parameter Field(description=...) — the model only sees …
      WARNING  timeout defaults to None but is typed as a non-optional type, so the schema advertises `"default": null` on a field whose `type` …
      ERROR  Bare 'except:' swallows all errors including cancellation — catch specific exceptions.

Repo-level
  ERROR  No README found.
  WARNING  No test files found.
  WARNING  No pyproject.toml/requirements.txt/setup.py/package.json/go.mod/Cargo.toml — dependencies aren't pinned.

$ mcp-doctor examples/good_server
mcp-doctor report
No known agent-breaking issues (checked: null defaults, stdout on stdio, mcp 2.x start-up)

Quality:  100%  Grade: A  (1 tool(s) found)
Security: 100%  Grade: A

  [OK] get_forecast (server.py:12)

mcp-doctor .                      # audit the current directory
mcp-doctor path/to/server         # audit a specific path
mcp-doctor . --json               # machine-readable output
mcp-doctor . --fail-under 80      # exit 1 if score drops below 80% — wire into CI
mcp-doctor . --diff               # preview the safe fixes as a patch (pipe to `git apply`); changes nothing
mcp-doctor . --fix                # apply safe, mechanical fixes in place, then re-report
mcp-doctor . --fix --fix-only none-default  # one kind of fix only (none-default, bare-except, args-stub), e.g. one kind per PR
mcp-doctor . --diff --llm         # same patch, with parameter docs drafted by a local model instead of TODOs

--fix only touches what's safe to fix without human judgment:

• None defaults typed nullable: name: str = None becomes name: str | None = None (or Optional[str] when the file already imports Optional); inside Annotated[...] only the type is wrapped. This is the