I built mcp-doctor — a free CLI + web tool that debugs your MCP servers in seconds

member_1ae7790c — Sun, 18 Oct 2026 18:36:03 +0000

The problem

You add an MCP server to your Claude Desktop or Cursor config. It doesn't show up. No error. You stare at mcp_settings.json for 40 minutes.

I've been there. The failure modes are boring and invisible: a typo in mcpServers, a missing package name for npx servers, a command that's not on your PATH, a server that starts but dies during the handshake, tool schemas that are technically valid but broken at runtime.

There is no standard tool to just... check it. So I built one.

mcp-doctor

A zero-dependency, single-file diagnostic engine for MCP server configurations. CLI + browser, no install required.

Paste your config → get a verdict:

npx github:420runingman420-blip/mcp-doctor --stdin < my-mcp-config.json

or open the web tool and paste your JSON:

👉 https://420runingman420-blip.github.io/mcp-doctor/

What it catches

mcpServers key typos (yes, this is the #1 bug I see)
missing/invalid command, args, url per server
npx servers with no @scope/pkg name (a silent no-op)
env referenced but not defined patterns
duplicate server entries
--live mode: actually spawns the server and completes the MCP initialize handshake, so you know it not just parses — it talks

Design notes

Zero npm dependencies. One checks.js module shared by the CLI and the browser build. Works on Node 18+.
The checks are plain functions returning {level, message} — easy to extend, easy to embed in your own CI.
Deterministic output (--json) for scripting.

Why I made it

MCP configs are the new .env — nobody reads them, everyone breaks them, and debugging is grep-and-pray. I wanted a doctor for them: flutter doctor, bundle doctor, mcp-doctor.

It's MIT licensed: https://github.com/420runingman420-blip/mcp-doctor

Try it

Copy your mcpServers block from Claude Desktop / Cursor / any MCP host
Paste it into the web tool (nothing leaves your browser)
Run --live on the CLI if you want the full handshake

Feedback welcome — issues and PRs on GitHub. If it saved you from a 40-minute stare, a star means a lot.