mcp-doctor
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-doctor
Live playground: https://mcp-doctor.kfairley9999.workers.dev
MCP configs fail quietly. A missing -y, a url where the client reads serverUrl, or an npx that a GUI cannot see on PATH looks like a client bug and is usually the config. mcp-doctor checks the file against the client that will load it, rewrites it for the client you actually use, and opens a real initialize handshake so you can see the failure.
Three surfaces, one library:
mcp-doctorCLI:validate,lint,convert,doctoran MCP server, so an agent can inspect the setup it is running inside
a Cloudflare Workers playground that checks a paste in the request and then drops it
The problem
There is still no standard MCP config schema. modelcontextprotocol/modelcontextprotocol#292 (51 thumbs-up) asks for one. Until it exists, every client invented a dialect:
Claude Desktop:
claude_desktop_config.jsonClaude Code:
.mcp.jsonCursor:
.cursor/mcp.jsonVS Code:
.vscode/mcp.jsonWindsurf:
mcp_config.jsonCline:
cline_mcp_settings.jsonCodex:
~/.codex/config.tomlGemini CLI:
~/.gemini/settings.jsonZed:
context_serversinsidesettings.json
The practical failures are well known. modelcontextprotocol/servers#64 (147 thumbs-up) is npx disappearing under nvm because GUI apps do not load the shell. cline/cline#902 is npx on Windows, which is a .cmd shim CreateProcess will not run. anthropics/claude-code#5826 is Claude Code refusing a custom server that was pasted from another client's example.
SchemaStore does not ship a schema for these filenames. Converters such as mcp-config-converter, mcp-config-sync, and mcp-installer copy or install a block. None of them validate it, lint it, or speak MCP to the server.
Related MCP server: MCP Doctor
Client support
"Yes" means the field survives a conversion into that client. A blank cell is reported as a drop, with the reason, instead of being invented.
Field | Claude Desktop | Claude Code | Cursor | VS Code | Windsurf | Cline | Codex | Gemini CLI | Zed |
Root key |
|
|
|
|
|
|
|
|
|
Format | JSON | JSON | JSONC | JSONC | JSON | JSON | TOML | JSON | JSONC |
command, args, env | yes | yes | yes | yes | yes | yes | yes | yes | yes |
cwd | yes | yes | yes | ||||||
envFile | yes | yes | |||||||
Remote URL |
|
|
|
|
|
|
|
| |
headers | yes | yes | yes | yes | yes |
| yes | yes | |
Timeout | ms | ms | seconds | ms | |||||
Disabled |
|
| |||||||
autoApprove | yes | ||||||||
trust | yes | ||||||||
SSE kept distinct | yes | yes | yes | yes ( | |||||
WebSocket | yes | ||||||||
Interpolation | none |
|
|
|
| none | none |
| none documented |
Sources for the golden fixtures: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex, Gemini CLI, Zed.
Cursor, Windsurf, and Zed store HTTP and SSE as the same URL. Conversion keeps the URL and says the transport label will not survive. Codex's url is streamable HTTP. Claude Desktop's JSON file only launches stdio. A remote server is omitted and reported. This tool does not wrap it in mcp-remote for you.
Lint rules
Each rule has a fix sentence. mcp-doctor lint --fix applies only the two edits that cannot change which program you meant: prepend -y, and split a command string into command plus args.
Rule | What it catches | Fix |
|
| Put |
|
|
|
| stdio command missing from | Absolute path, or install it. Needs a local probe. |
|
| Point |
|
| Export it where the client can see it. GUI apps skip the shell rc. |
|
| Rewrite to the form that client expands. |
| Tokens, keys, URL passwords, placeholders | Use the client's interpolation. The message does not echo the value. |
|
| Rename to the field that client reads. |
|
| Set the type the client documents. Cline with no type means SSE. |
| stdio entry with no command | Set |
| http/sse/ws entry with no URL | Set the URL field. |
|
| Split it. Clients do not run a shell. |
|
| Absolute path. |
|
| Use https. Credentials on cleartext are an error. |
|
| Match the unit. |
lint prints text, --format json, or --format sarif. Warnings exit 0 unless --strict. Errors exit 1.
Install
npm ci
npm run buildThe CLI is node packages/cli/dist/main.js, also npm run mcp-doctor -- <args> from the repo root. This package is not published to npm, and the npm name mcp-doctor belongs to an unrelated package, so npm install mcp-doctor does not install this tool.
npm run mcp-doctor -- validate .cursor/mcp.json --client cursor
npm run mcp-doctor -- lint .mcp.json --format sarif
npm run mcp-doctor -- convert claude_desktop_config.json --from claude-desktop --to windsurf
npm run mcp-doctor -- doctor --timeout 10000doctor discovers the config files listed above, lints them, and performs an MCP initialize handshake (stdio, streamable HTTP, and a best-effort SSE connect) with a timeout. It only reads config files. It does start the servers those files name. Pass --home and --root to look somewhere other than your real home, and --no-handshake to skip the spawn.
A file of - reads stdin. convert writes the config to stdout and the carry report to stderr, so the config can be piped.
MCP server
The server speaks stdio through @modelcontextprotocol/sdk and exposes validate_config, lint_config, convert_config, diagnose_server, and list_client_configs. diagnose_server is the handshake. list_client_configs does not start servers.
Build first (npm run build), then point the client at packages/mcp-server/dist/main.js. Use the absolute path on your machine.
Claude Desktop, claude_desktop_config.json:
{
"mcpServers": {
"mcp-doctor": {
"command": "node",
"args": ["/absolute/path/to/mcp-doctor/packages/mcp-server/dist/main.js"]
}
}
}Cursor, .cursor/mcp.json or ~/.cursor/mcp.json:
{
"mcpServers": {
"mcp-doctor": {
"command": "node",
"args": ["/absolute/path/to/mcp-doctor/packages/mcp-server/dist/main.js"]
}
}
}Claude Code, .mcp.json:
{
"mcpServers": {
"mcp-doctor": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/mcp-doctor/packages/mcp-server/dist/main.js"]
}
}
}Architecture
flowchart LR
subgraph surfaces
CLI["CLI validate lint convert doctor"]
MCP["MCP server stdio"]
WEB["Workers playground"]
end
CORE["@mcp-doctor/core"]
NODE["core/node discover and handshake"]
CLI --> CORE
CLI --> NODE
MCP --> CORE
MCP --> NODE
WEB --> CORE
CORE --> SCHEMAS["JSON Schemas per client"]
CORE --> LINT["15 lint rules"]
CORE --> CONV["parse and emit"]
NODE --> COREThe playground imports only the pure library. Handshake and PATH checks need a process, and running them on Cloudflare would execute whatever command was pasted. They stay on the machine.
Playground
Paste a config, see validation, lint, and the same servers emitted for every client. The page posts the text (up to 64KB) to /api/analyze on this Worker. The Worker answers and discards the body. It does not log the body, store it, or send it anywhere else.
Live demo: https://mcp-doctor.kfairley9999.workers.dev (Cloudflare Workers free tier).

Deploy
The live demo runs on the Cloudflare Workers free tier. CI runs the dry run and does not deploy. Nothing in the Worker uses a paid binding. No secrets, no KV, no D1.
cd playground
npx wrangler login
npx wrangler deploynpm run playground:dry-run from the repo root bundles the Worker and stops before upload. Local preview:
npx tsc -b packages/core
npm run dev -w mcp-doctor-playgroundThat listens on port 47471.
Development
npm ci
npm test
npm run test:coverage
npm run lint
npm run schemas:validateCI on Node 20 and 22 runs lint, typecheck, tests with the 85% coverage gate, and schema self-validation. The playground bundle and wrangler deploy --dry-run run on Node 22 only, because Wrangler 4 requires Node 22.12 or newer.
Limitations
The schemas follow public docs as of November 2026. Clients change fields without a spec. A passing schema means the shape is one they document, not that this week's build still accepts it.
Same-client emit is stable in the canonical model, not byte-for-byte. Codex comments and key order are not preserved. Zed's legacy
{ command: { path } }object is read and written back in the flat form.~/.claude.jsonholds project-scoped servers underprojects.doctorreads those.convertrewrites the top-levelmcpServersmap.doctoranddiagnose_serverrun the configured command. They are not a sandbox. Review the file first.A green
PATHcheck in the terminal can still fail inside Claude Desktop or Cursor, because those processes do not source your shell. The version-manager rule exists for that case and can still miss a manager it cannot see without launching a shell.WebSocket handshake is not implemented. SSE is a short read for the
endpointevent, then one POST.Nested interpolation such as
${A:-${B}}is not modeled. Claude Code's credential names that expand to empty are not special-cased.The playground cannot check
PATH, nvm, or a live server. Doing so would run untrusted commands and contact arbitrary URLs.Not published to npm. Not submitted to SchemaStore.
Roadmap
Submit the schemas to SchemaStore once a client freezes a shape.
Fixes for the mechanical renames (
urltoserverUrl,${env:VAR}to${VAR}) behind an explicit flag.A file watcher for
lint.Continue, Roo, and other clients that copy one of these dialects.
A fuller SSE and WebSocket handshake.
How it was built
Designed and directed by Kevin Fairley, built with AI coding agents.
MIT license. See CONTRIBUTING.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Convert, lint and generate LLM tool schemas for OpenAI, Anthropic, Gemini and MCP
Free, no-key MCP server: token estimates, JSON Schema conversion, MCP configs, tool search.
MCP Spec Compliance MCP — audits any MCP server.json against the official Model Context Protocol
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to run project-specific checks, replays, simulations, and queries as MCP tools, providing ground-truth feedback on config edits instead of guessing.1MIT
- AlicenseAqualityBmaintenanceProvides health checks, binary validation, and auto-repair for MCP configurations in Claude Desktop, Cursor, and Cline.315 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables any MCP client to detect Claude Code configuration that is silently ignored, such as agent files that fail to load, unknown frontmatter fields, parent-folder settings, conflicting MCP server entries and drift since a baseline. Exposes read-only tools that return findings with exact edits, the fix prompt, and explanations of each check, without modifying any files.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables agents to inspect and diagnose their own MCP setup by exposing read-only tools that audit configured servers, report which coding agents have configs, surface misplaced or duplicated registrations, and list curated preset packs. It also powers CLI workflows for checking handshake, tool lint, and tool-surface quality scores of any stdio server.32 npmMIT