Migrationpilot

What migrationpilot does

The migrationpilot MCP server gives AI coding agents access to local, deterministic PostgreSQL migration analysis. It is designed to identify statements that may block production traffic, acquire severe locks, or violate migration-safety rules before an agent writes or applies DDL.

The server checks 112 rules and can return violations, a risk score, lock information, and suggested safer SQL. Its main gate is check_before_apply, which accepts migration SQL and returns a pass or fail verdict, the configured failure threshold, detected violations, and a summary. This makes it suitable for placing a safety check immediately before a migration is applied.

Analysis does not require a database connection.

How it works

Configure the MCP server with the command npx migrationpilot-mcp. The agent can then call tools over MCP and provide SQL directly. The server uses the same .migrationpilotrc.yml resolution behavior as the command-line interface, allowing check_before_apply to use the project’s configured rules and failure level.

For a single migration, analyze_migration reports rule violations, risk, and lock analysis. analyze_migration_dir evaluates multiple files and produces both per-file results and an aggregate. explain_lock focuses on the lock acquired by one DDL statement and the operations it can block.

The tool output distinguishes warning and critical findings. In the CLI, clean analysis exits with code 0, warnings can produce code 1 when configured with --fail-on warning, and critical findings produce code 2. The MCP gate exposes a pass or fail result based on its configured threshold.

Tools and capabilities

The migrationpilot MCP server provides these seven tools:

• check_before_apply: Apply a configured pass/fail gate to SQL.
• analyze_migration: Inspect one migration for violations, risk, and locks.
• analyze_migration_dir: Analyze a directory and aggregate its results.
• get_rule: Read what a rule detects, why it matters, and whether it supports an automatic fix.
• suggest_fix: Return fixed SQL where possible and identify issues requiring human review.
• explain_lock: Describe a DDL statement’s lock and what it may block.
• list_rules: Return the complete rule catalogue.

The README gives an example where adding a unique constraint triggers findings for an ACCESS EXCLUSIVE lock and for building a unique index under that lock. The suggested alternative creates the index concurrently before attaching it as a constraint.

Setup and configuration

Run the server through an MCP client with a configuration equivalent to:

{
  "mcpServers": {
    "migrationpilot": {
      "command": "npx",
      "args": ["migrationpilot-mcp"]
    }
  }
}

The CLI requires Node.js 22 or newer, and the PostgreSQL parser is included in the package. Project configuration can be supplied through .migrationpilotrc.yml; check_before_apply also accepts an optional configPath and PostgreSQL version input.

Claude Code includes a separate plugin with a skill and a pre-tool-use hook. Cursor can use the provided .mdc rule file. These are client integrations in addition to the MCP server configuration.