mcp-skill-doctor

[](./LICENSE) [](https://www.typescriptlang.org/) [](https://pnpm.io/) [](https://github.com/Hazel-Lin/mcp-skill-doctor/releases)

Local-first CLI to diagnose why your MCP server or skill will not start.

It checks the boring but expensive stuff first: PATH, cwd, required env vars, missing files, and processes that exit before the client can use them.

If you build MCP servers or agent skills, this is the quick pre-flight check worth keeping around.

中文版本请见 README.zh-CN.md.

• Inspector helps after a server is already reachable
• Validator checks protocol compliance
• mcp-skill-doctor finds the reason your local setup fails before either of those help

Try pnpm run check:broken to see a realistic failure report.

• Command not found in PATH
• Missing cwd or referenced file
• Missing required environment variables
• Processes that exit immediately
• Transport mismatch for local stdio setups

• Diagnose local stdio MCP server startup issues
• Validate command availability, config shape, working directory, and required environment variables
• Probe whether the target process starts cleanly or exits immediately
• Print actionable PASS / WARN / FAIL results with remediation hints

• Small enough to understand in one sitting
• Useful every time you wire up a new MCP server
• Easy to run locally and easy to share with teammates
• Built around real startup friction, not abstract spec talk

pnpm install
pnpm run check:valid
pnpm run probe:fake

{
  "name": "example-server",