你往 Claude Desktop 或者 Cursor 的配置里加了一个 MCP 服务器。它没出现。没有报错。你盯着mcp_settings.json看了40 分钟。

这个场景，mcp-doctor 的作者说自己经历过。失败模式无聊又隐形：mcpServers拼写错了、npx 服务器缺了包名、命令不在 PATH 上、服务器启动了却在握手阶段挂掉、工具 schema 语法上合法但运行时是坏的。

没有一个标准工具能"就……检查一下"。于是他做了一个。

mcp-doctor是一个零依赖、单文件的 MCP 服务器配置诊断引擎，CLI 和浏览器都能用，不用安装。用法很直接：把配置贴进去，拿一个判定结果。命令行走--stdin读入 JSON，或者打开网页工具粘贴配置——按作者的说法，粘贴的内容不会离开浏览器。

它能抓的东西列得很具体：

  • mcpServers键名拼写错误——作者说这是他见过最多的头号 bug
  • 每个服务器缺失或非法的commandargsurl
  • npx 服务器没写@scope/pkg包名，属于静默空操作
  • 引用了env变量却没定义的模式
  • 重复的服务器条目
  • --live模式：真的把服务器拉起来，完整跑一遍 MCP 的initialize握手，所以它不只是解析配置，它真的在对话

设计上有几个取舍值得说。零 npm 依赖，CLI 和浏览器构建共用同一个checks.js模块，Node 18 以上可用。检查项都是普通函数，返回{level, message}，方便扩展，也方便塞进你自己的 CI。输出是确定性的，带--json，方便脚本处理。

作者给这个工具找的定位挺有意思：MCP 配置就是新的.env——没人读它，人人弄坏它，调试靠 grep 加祈祷。他想要一个 doctor，就像flutter doctor、bundle doctor那样，于是有了 mcp-doctor。

项目是 MIT 协议开源的。想试的话，从 Claude Desktop、Cursor 或任何 MCP 宿主里把mcpServers那段复制出来，贴进网页工具；想要完整握手，就在 CLI 上跑--live。作者在 GitHub 上收 issue 和 PR，原话是：如果它帮你省下了那 40 分钟的凝视，一个 star 意义很大。