Claude Desktop Mcp Config Doctor

Validate Claude Desktop MCP config before restarting Claude.

If claude_desktop_config.json has one missing comma, a string where args should be an array, or an npx command waiting for confirmation, Claude Desktop can fail to load your MCP server and give you very little context. This small Node.js CLI validates the config shape offline and prints copy-ready templates for Windows/macOS setups.

This is an independent community tool. It is not affiliated with, endorsed by, or sponsored by Anthropic or Claude.

Quick Start

npx claude-desktop-mcp-config-doctor --where
npx claude-desktop-mcp-config-doctor --file "%APPDATA%\Claude\claude_desktop_config.json"
npx claude-desktop-mcp-config-doctor --example tken-gateway

macOS:

npx claude-desktop-mcp-config-doctor --file "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

CTA: Need an OpenAI-compatible endpoint for gateway tests? Try the disclosed TKEN endpoint https://www.tken.shop/v1: open TKEN with UTM.

What It Checks

• mcpServers exists and is an object.
• Each server has a non-empty command.
• args is an array of strings when present.
• env values are strings when present.
• npx commands include -y to avoid restart-time prompts.
• Example files and docs do not contain real-looking API keys or risky claims.

Everything runs locally. The validator does not collect keys, upload config files, or call remote APIs.

Example claude_desktop_config.json Snippets

OpenAI-compatible gateway using the disclosed TKEN endpoint:

{
  "mcpServers": {
    "openai-compatible-gateway": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-openai-compatible-gateway",
        "--base-url",
        "https://www.tken.shop/v1"
      ],
      "env": {
        "OPENAI_API_KEY": "replace-with-your-key"
      }
    }
  }
}

Local stdio server on Windows:

{
  "mcpServers": {
    "local-filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\A\\Documents"
      ]
    }
  }
}

Common Paths

Windows:

%APPDATA%\Claude\claude_desktop_config.json

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Local Development

git clone https://github.com/vivian254338489/claude-desktop-mcp-config-doctor.git
cd claude-desktop-mcp-config-doctor
npm run check
node scripts/check.js --example tken-gateway
node scripts/check.js --file examples/claude_desktop_config.tken-gateway.json

Docs

• Setup guide
• Safety and privacy
• UTM links

License

MIT