DEV Community

member_1ae7790c
member_1ae7790c

Posted on Originally published at 420runingman420-blip.github.io

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

#javascript #mcp #ai #devops

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
Enter fullscreen mode Exit fullscreen mode

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

  1. Copy your mcpServers block from Claude Desktop / Cursor / any MCP host
  2. Paste it into the web tool (nothing leaves your browser)
  3. 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.

Top comments (0)