MCP Database Doctor

MCP Database Doctor

Catch dangerous PostgreSQL migrations and slow queries before your AI agent ships them — offline, no DB credentials.

Offline PostgreSQL migration linting and query analysis for AI coding agents. Detects table-locking DDL, dangerous type changes, slow query patterns, and execution plan issues before they reach production. Nothing leaves your machine, no database connection required.

---

Quick Install

Cursor

Click the button above to install in one step, or use this link: cursor://anysphere.cursor-deeplink/mcp/install?name=database-doctor&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1kYXRhYmFzZS1kb2N0b3IiXX0=

Or add manually to ~/.cursor/mcp.json:

{

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

Claude Code

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

Or, if available in the Cursor plugin marketplace:

/plugin marketplace add petrovicistefan/mcp-marketplace

Claude Desktop

Add to claude_desktop_config.json:

{

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

VS Code

Or add to .vscode/mcp.json:

{

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

Any MCP Client

npx -y mcp-database-doctor

⭐ Star this repository to support the project and stay updated! → Give a star

---

📋 Table of Contents

• Why Database Doctor?
• Use Cases
• What It Checks
• How It Compares
• Tools
• Example Prompts
• Limitations
• Development
• More MCP Servers by the Author
• Contributing
• License

---

Why Database Doctor?

The hook: Your AI agent generates migrations that *look* harmless: CREATE INDEX, ALTER COLUMN ... TYPE, ADD COLUMN NOT NULL. But each one can lock your production table for minutes or hours, block every write, and take down your app.

Database Doctor catches these before they ship:

• No database required: Static analysis only, works with uncommitted code
• No credentials: Nothing connects to your database or executes SQL
• No network: Everything runs locally on your machine
• AI-native: Designed for AI coding agents (Claude Code, Cursor, GitHub Copilot)

When to Use

✅ Before shipping migrations — Catch CREATE INDEX without CONCURRENTLY, dangerous type changes, volatile defaults ✅ Reviewing slow queries — Detect SELECT *, deep OFFSET, unbounded writes, unindexed predicates ✅ Analyzing EXPLAIN plans — Spot large sequential scans, row estimate errors, sort spills, high loop counts ✅ Suggesting indexes — Get conservative DDL candidates for WHERE clause columns

---

Use Cases

1. AI Agent Code Review

Your agent writes the migration. Database Doctor reviews it before committing.

User: "Add an email column to the users table"

Agent writes: ALTER TABLE users ADD COLUMN email VARCHAR(255) NOT NULL;

Database Doctor flags: ⚠️ NOT_NULL_CHANGE (medium severity) Adding NOT NULL requires a full table scan and may hold locks. Recommendation: Backfill data first, then add NOT NULL separately.

Agent rewrites: ALTER TABLE users ADD COLUMN email VARCHAR(255); -- Backfill in application code or batched UPDATE ALTER TABLE users ALTER COLUMN email SET NOT NULL;

2. Pre-Commit Checks

Catch dangerous migrations before they reach CI.

Ask your AI: *"Check all migrations in db/migrations/ for safety"*

Database Doctor reviews each file and reports:

• Destructive DDL (DROP, TRUNCATE)
• Blocking index creation
• Table-rewriting column changes
• Constraint validation without NOT VALID
• Transactions that can't hold CONCURRENTLY operations

3. Query Optimization

Find performance issues before they hit production.

Your agent generates:

SELECT * FROM orders 

WHERE LOWER(email) = 'user@example.com' OFFSET 10000 LIMIT 20;

Database Doctor flags:

• SELECT_STAR: Wildcard projection couples schema to caller
• FUNCTION_PREDICATE: LOWER() may not use an index on email
• DEEP_OFFSET: Offset 10000 discards many rows, use keyset pagination

4. EXPLAIN Plan Review

Submit a slow query's execution plan for analysis.

# On your test database

EXPLAIN (FORMAT JSON) SELECT ... > plan.json

In your AI client

"Review this execution plan from plan.json"

Database Doctor detects:

• Sequential scans on large tables
• Row estimate errors (10x+ off)
• Sort operations spilling to disk
• High loop counts in nested joins

---

What It Checks

Migration Safety (check_migration)

Query Analysis (analyze_query)

EXPLAIN Plan Analysis (explain_plan)

---

How It Compares

*As of October 2026. All comparisons stated cautiously based on public documentation.*

Our differentiators:

• Broadest scope: migrations + queries + EXPLAIN plans + index suggestions (4 capabilities in one tool)
• Zero setup: No database, no credentials, no config — works on uncommitted code
• Privacy-first: Completely offline, nothing sent anywhere
• PostgreSQL-native: Not regex-based, handles comments, strings, dollar quotes, nested blocks
• Lightweight: Zero dependencies beyond MCP SDK and Zod

When to use alternatives:

• MigrationPilot: Need 112 rules, auto-fix, VS Code extension, GitHub Action with SARIF
• Locksmith: Need paste-ready safe rewrites and lock matrix documentation
• Ballast: Need load-aware analysis weighted by real table size (requires DB connection)
• DBHub: Need to connect to live databases for exploration and guarded SQL execution

---

Tools

Database Doctor exposes 5 MCP tools for AI agents:

| suggest_indexes | sql (string) existingIndexes (optional array) | Conservative index DDL candidates (never applied, requires EXPLAIN validation) | | explain_plan | plan (JSON string) | Large scans, row estimate errors, sort spills, high loops | | health_report | queries (optional array) migrations (optional array) plans (optional array) | Aggregate review of supplied artifacts (not live database health) |

All tools are read-only, idempotent, and require no authentication.

Reports include:

• code: Stable identifier for the finding type
• severity: high, medium, or low
• message: What the issue is
• recommendation: How to fix it
• statement: Which statement in multi-statement SQL (1-indexed)

---

Example Prompts

For migrations:

"Check this migration for locking issues"

"Review db/migrations/003_add_email_index.sql before I commit" "Is this ALTER TABLE safe for a production table with 10M rows?"

For queries:

"Analyze this query for performance issues"

"Why is this SELECT slow?" "Review the queries in src/repositories/user.ts"

For EXPLAIN plans:

"Review this EXPLAIN plan from plan.json"

"What's wrong with this execution plan?"

**For index sugges