MCP Database Doctor

What MCP Database Doctor does

MCP Database Doctor MCP server provides offline checks for PostgreSQL-related artifacts supplied by an AI agent or developer. It does not accept database credentials, connect to a PostgreSQL instance, run SQL, or execute EXPLAIN ANALYZE. Instead, it reviews SQL text and JSON plans locally and reports findings for further human or workload-based validation.

The server fits the 🗄️ Databases category and is intended for development workflows that need an initial review before database changes are proposed. Reports contain a finding code, severity, explanatory message, recommendation, and statement numbers for SQL findings. The aggregate health report summarizes submitted artifacts; it does not produce a synthetic database health score.

How it works

The server runs as a local MCP process over stdio. Clients send SQL, migration text, index metadata, or an EXPLAIN plan as tool inputs. The implementation applies static, heuristic rules and returns structured findings without sending data to a remote analysis service. No account or API key is needed for the local setup, and local analysis has no telemetry.

MCP Database Doctor MCP server can also be run through a separate hosted HTTP process. That path reserves usage units through mcp-control-plane before analysis and requires authorization. The hosted process keeps SQL and plans on its host; the control plane receives the product, request ID, and unit information. Local MCP operation remains separate from hosted quotas.

Setup and configuration

The package can be launched with npx -y mcp-database-doctor and added to an MCP client's stdio configuration. The README documents configurations for Claude Code, Codex CLI, Claude Desktop, Cursor, Windsurf, Cline, Gemini CLI, VS Code with GitHub Copilot, and Zed. A locally built checkout can instead launch dist/server.js with Node and an absolute path.

For hosted operation, build the project, set CONTROL_PLANE_URL in the environment, and run the hosted start command. The hosted HTTP process listens on 127.0.0.1:3103 by default. Local use does not require database credentials or API keys.

Tools and capabilities

• analyze_query reviews SQL for anti-patterns and returns severity levels and recommendations.
• check_migration examines destructive DDL, index-locking concerns, constraint changes, table rewrites, and transaction risks.
• suggest_indexes produces conservative, unapplied DDL candidates. It accepts optional existing-index information.
• explain_plan inspects a JSON-string plan for large sequential scans, row-estimate errors, sort spills, and high loop counts.
• health_report reviews supplied query, migration, and plan arrays when at least one array is provided.

Index inference is intentionally narrow: it supports one unquoted table without joins or subqueries. Supplied existing indexes can suppress candidates when a matching leading column is present, but partial and expression indexes still need manual review.

Limitations and notes

MCP Database Doctor MCP server is PostgreSQL-first rather than a full SQL parser. It masks comments, string and dollar-quoted literals, and quoted identifiers, but stored procedures, DO blocks, dynamic strings, complex CTEs, nested scopes, aliases, quoted or schema-qualified names, and unusual DDL can produce missed findings or false positives.

The documented limits are 100,000 characters per SQL input, 1 MB per plan string, 100 artifacts per report, and 10,000 plan nodes. Migration checks rely on transaction boundaries present in the supplied script; if a framework wraps the script externally, include that context when checking concurrent indexes.

A finding-free result is not approval to run a query or migration. Index suggestions are candidates, not applied changes, and plan review does not determine that an index is necessarily better. Obtain real plans separately in a safe environment, remembering that EXPLAIN ANALYZE executes the statement. The project is marked as a 0.1.0 MVP, and real PostgreSQL and host validation were still pending in the provided material.