MCP Database Doctor

Offline PostgreSQL diagnostics for AI coding agents. Review SQL, risky migrations, candidate indexes and supplied EXPLAIN JSON plans without database credentials or executing statements.

Status: 0.1.0 MVP. Static rules are heuristic: no_rules_triggered does not mean safe, performant or valid PostgreSQL. No telemetry, remote analysis, credentials or automatic fixes.

Install in your AI client

Works with any MCP client over stdio; no account or API key needed for the local server.

Claude Code

claude mcp add database-doctor -- npx -y mcp-database-doctor

Codex CLI

codex mcp add database-doctor -- npx -y mcp-database-doctor

Claude Desktop, Cursor, Windsurf, Cline, Gemini CLI — add to the client's MCP config (claude_desktop_config.json, ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, Cline MCP settings, ~/.gemini/settings.json):

{
  "mcpServers": {
    "database-doctor": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-database-doctor"
      ]
    }
  }
}

VS Code / GitHub Copilot — .vscode/mcp.json:

{
  "servers": {
    "database-doctor": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-database-doctor"
      ]
    }
  }
}

Zed — settings.json:

{
  "context_servers": {
    "database-doctor": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-database-doctor"
      ]
    }
  }
}

Related MCP server: SQL Query Optimizer

Tools

Reports include code, severity, message, recommendation, and statement numbers for SQL. No synthetic database health score.

Development

Node.js >=22.18 (Node 24 recommended).

npm install
npm run check
npm test
npm run build
npm run test:integration
npm pack --dry-run

Core tests run without installed dependencies using Node's native TypeScript stripping. Vitest integration tests exercise the official MCP client over stdio after build. CI runs both. Generate and commit a package-lock.json after the first successful dependency installation; current checkout does not include one because npm access was blocked in the implementation environment.

Claude Code / Cursor

Build locally first. Copy examples/mcp.json into your client's MCP configuration and replace the absolute checkout path:

{
  "mcpServers": {
    "database-doctor": {
      "command": "node",
      "args": ["/absolute/path/mcp-database-doctor/dist/server.js"]
    }
  }
}

Claude Code CLI alternative:

claude mcp add database-doctor -- node /absolute/path/mcp-database-doctor/dist/server.js

Launch with npx -y mcp-database-doctor.

Suggested agent instruction: "Before proposing database changes, call check_migration. Review slow queries with analyze_query and supplied EXPLAIN JSON. Treat index DDL as candidates requiring workload validation."

Examples

check_migration({"sql":"BEGIN; CREATE INDEX CONCURRENTLY ON users(email); COMMIT;"}) identifies an invalid transaction context.

analyze_query({"sql":"SELECT * FROM users OFFSET 50000"}) flags projection and deep pagination.

explain_plan({"plan":"[{\"Plan\":{\"Node Type\":\"Seq Scan\",\"Plan Rows\":20000}}]"}) flags a scan for review; it does not claim an index is necessarily better.

For a real database, obtain plans yourself on a safe test environment: EXPLAIN (FORMAT JSON) SELECT .... EXPLAIN ANALYZE executes the statement; this server never runs it.

Limits and interpretation

• PostgreSQL-first, not a full SQL parser. Comments and string/dollar literals are masked. Quoted identifiers are masked to avoid keyword confusion.

• SQL inside stored procedures, DO blocks and dynamic strings is not analyzed. Complex CTEs, nested scopes, aliases, quoted/schema names and unusual DDL can produce false positives or missed findings.

• Index inference intentionally supports one unquoted table without joins/subqueries. No schema metadata, statistics, foreign-key index analysis or composite-index optimization. Existing indexes only suppress candidates when their supplied leading column matches; partial/expression indexes need manual review.

• Migration checks assume the supplied script defines transaction boundaries. If a migration framework wraps scripts externally, provide its BEGIN/COMMIT context when checking concurrent indexes.

• 100000 characters per SQL, 1 MB per plan string, 100 artifacts per report, 10000 plan nodes. These are analysis limits, not a substitute for host transport limits.

• Findings are review prompts. Absence of a finding is not authorization to run a migration.

Hosted path (quotas via control plane)

Local MCP stays free and offline. Quotas apply only on a hosted HTTP process that reserves units on mcp-control-plane before analysis. Build first (npm run build), then:

cp .env.example .env   # set CONTROL_PLANE_URL
npm run start:hosted   # default 127.0.0.1:3103

Requires Authorization: Bearer mcp_…. SQL and plans stay on the hosted host; control-plane sees only product, requestId, and units. No database credentials are accepted.

Commercial roadmap

Free: local query/migration/plan analysis. Pro later: history, before/after comparisons, CI policies and advanced recommendations. Team later: shared policies and centralized reports. Hosted quotas use the control-plane path above; local counters are not used for paid enforcement.

Validation status

• 53 core tests passed in the implementation environment.

• Typecheck/build/MCP stdio integration: configured, not run locally (npm registry returned HTTP 403).

• Real PostgreSQL and two actual AI hosts: pending; configuration files do not constitute host integration validation.

References

• https://ts.sdk.modelcontextprotocol.io/server

• https://www.postgresql.org/docs/current/sql-createindex.html

• https://www.postgresql.org/docs/current/using-explain.html

MIT license.

⭐ Support this project

Found this MCP useful? Star this repository!

A GitHub star helps other developers discover the project and lets you save it for later. Thanks for supporting open source!