live · 2026

MCP Doctor

An open-source, local-first CLI that turns common MCP configuration failures into clear, actionable fixes.

View on GitHub

Terminal interface captured from MCP Doctor CLI v0.1.0.

Problem

MCP configuration and environment failures often look like agent crashes, creating friction and slow debugging cycles.

Role & Contribution

Product Concept, System Architecture, CLI Design, Open-Source Engineering

Duration

Open source (v0.1.0)

Status / Outcome

live

Context: The MCP configuration debugging gap

Model Context Protocol (MCP) allows AI agents to connect to local tools and data sources. However, when an MCP server fails to start, developers often struggle to isolate the root cause. Apparent agent failures frequently stem from unglamorous configuration issues:

Malformed JSON syntax or illegal trailing commas
Executables present in terminal shells but missing from GUI application PATH environments
Referenced environment variables or secret API keys left unexported
Unpinned npx or package runners triggering interactive prompts during silent background startup
Logging statements written to stdout before the protocol handshake completes
Literal API keys or sensitive tokens stored directly in version-controlled config files

MCP Doctor was created as an open-source CLI tool to bridge this gap: turning cryptic startup failures into precise, automated diagnostic reports with actionable repair instructions.

MCP Doctor CLI terminal output displaying discovered configuration path, diagnostic execution, and structured error/warning reports — MCP Doctor CLI output: Scanning an MCP configuration file, categorizing issues by severity, and detailing exact repair steps.

Core product principles

Local-First Safety

MCP configs contain private paths and environment keys. Inspection happens entirely on the local machine with zero network transmission.

Actionable Guidance

Every finding pairs a human-readable description with an explicit repair suggestion to minimize time-to-resolution.

Human & Automation Friendly

Supports clean terminal text output for interactive use, structured JSON for tools/scripts, and strict exit status codes (0, 1, 2).

Diagnostic engine architecture

MCP Doctor operates through a multi-stage pipeline designed to parse, normalize, and audit configurations across multiple client formats (Claude Desktop, Cursor, Continue, etc.) without runtime dependencies.

System architecture diagram of MCP Doctor showing discovery, strict JSON parsing, normalization, and the 7-territory rule pipeline — Diagnostic Pipeline: Config discovery, JSON parsing, shape normalization, and 7 territory rule inspections.

Designing the finding model

To serve both interactive developers and automated CI check scripts, every finding follows a structured model:

{
  "severity": "error",
  "code": "missing-env-var",
  "server": "postgres-mcp",
  "message": "Referenced environment variable is not set: DATABASE_URL",
  "fix": "Export DATABASE_URL in your shell or specify it in client launcher env.",
  "category": "runtime",
  "confidence": "high",
  "location": "mcp.json#mcpServers.postgres-mcp.env.DATABASE_URL"
}

Diagnostic Coverage (v0.1.0 Shipped Capabilities)

Syntax & Structure: Readability, strict JSON validation, supported server object keys
Runtime & Executables: Binary presence, absolute path verification, script location checks
Environment & Security: Unset variables, hardcoded API key tokens in CLI arguments
Startup Protocol: Detection of unpinned npx/uvx prompts and stdout logging risks
Supply Chain: Package version pinning verification
Metadata & Usability: Zero-width unicode characters, confusable names, prompt budget limits

Engineering delivery & roadmap

MCP Doctor v0.1.0 was built with zero runtime dependencies using standard Node.js APIs (Node 20+). It includes a native test suite (node --test) covering 6 key failure scenarios to prevent false positives.

Open Source Availability: The project is published under the MIT license at github.com/WestsideUnion/mcp-doctor ↗