MCP Database Doctor MCP server

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: norulestriggered 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 (claudedesktopconfig.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"
      ]
    }
  }
}

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 checkmigration. Review slow queries with analyzequery 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.

analyzequery({"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.

Shortened. The full README is on GitHub.