@mhdd_24/flyway-mcp

MCP server that runs Flyway repair + migrate across multiple database projects for QA or Development environments. Use it from Cursor, Claude Desktop, VS Code Copilot, or any MCP-compatible client.

Say "QA Flyway Migration" or "Dev Flyway Migration" in chat — the assistant calls the matching tool automatically.

Full documentation: docs/WIKI.md

How it works (30 seconds)

You (chat) → MCP client → flyway-mcp → discover projects under FLYWAY_ROOT
                                    → flyway repair + migrate (per project)
                                    → auto-remediate common errors → retry

1. Discovery — finds subfolders with flyway.toml and flyway_qa.toml / flyway_dev.toml

2. Repair — fixes schema history checksums before migrate

3. Migrate — applies pending migrations per environment config

4. Remediation — on failure, attempts automatic fixes (duplicate versions, placeholders, missing tables) and retries

Prerequisites

Expected project layout

Each project is a subfolder under FLYWAY_ROOT:

flyway-projects/
├── service-a-db/
│   ├── flyway.toml
│   ├── flyway_qa.toml
│   ├── flyway_dev.toml
│   └── migrations/
└── service-b-db/
    ├── flyway.toml
    └── migrations/

Install

Option A — npm (recommended)

npm install -g @mhdd_24/flyway-mcp

Option B — npx (no global install)

npx @mhdd_24/flyway-mcp

Option C — clone and build (contributors)

git clone https://github.com/Mhdd-24/Flyway-MCP.git
cd Flyway-MCP
npm install
npm run build
node dist/index.js

Configure your MCP client

Cursor

Edit Cursor Settings → MCP or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "flyway": {
      "command": "npx",
      "args": ["-y", "@mhdd_24/flyway-mcp"],
      "env": {
        "FLYWAY_ROOT": "/path/to/your/flyway-projects",
        "FLYWAY_CLI": "flyway",
        "FLYWAY_MAX_RETRIES": "3"
      }
    }
  }
}

After global install:

"command": "flyway-mcp"

Local development:

"command": "node",
"args": ["C:/path/to/flyway-mcp/dist/index.js"]

Restart Cursor after saving.

Optional: limit projects

"FLYWAY_PROJECTS": "service-a-db,service-b-db"

Environment variables

Never commit database credentials. Keep connection strings in flyway_qa.toml / flyway_dev.toml inside each project (not in MCP env).

Tools

Optional parameters

Usage

List projects

List flyway projects

QA migration (all projects)

QA Flyway Migration

Dev migration (single project)

Dev Flyway Migration for service-a-db

Automatic remediation

On migration failure, the server may automatically:

Some errors (e.g. missing database plugins) cannot be auto-fixed and are reported in the summary.

Troubleshooting

More detail: docs/WIKI.md

License

ISC