@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

Discovery — finds subfolders with flyway.toml and flyway_qa.toml / flyway_dev.toml
Repair — fixes schema history checksums before migrate
Migrate — applies pending migrations per environment config
Remediation — on failure, attempts automatic fixes (duplicate versions, placeholders, missing tables) and retries

Prerequisites

Requirement	Notes
Node.js 18+	Required for MCP server
Flyway CLI	On PATH (`flyway -v` works)
Java	Required by Flyway
FLYWAY_ROOT	Path to folder containing your Flyway project directories

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

Variable	Required	Default	Purpose
`FLYWAY_ROOT`	Yes	—	Root folder containing Flyway project directories
`FLYWAY_CLI`	No	`flyway`	Flyway executable name or path
`FLYWAY_PROJECTS`	No	all	Comma-separated project folder names to include
`FLYWAY_MAX_RETRIES`	No	`3`	Repair/migrate/fix retry cycles per project

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

Tools

Tool	Trigger phrase	Purpose
`list_flyway_projects`	List flyway projects	Shows discovered projects and QA/Dev config availability
`qa_flyway_migration`	QA Flyway Migration	`repair` + `migrate` using `flyway_qa.toml`
`dev_flyway_migration`	Dev Flyway Migration	`repair` + `migrate` using `flyway_dev.toml`

Optional parameters

Parameter	Applies to	Description
`projects`	migration tools	Array of project folder names (default: all discovered)

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:

Error	Fix
Duplicate migration version	Renames duplicate files to next available version
Checksum mismatch	Runs `repair` and retries
JS placeholder (`${dbName}`)	Removes/replaces Flyway placeholder tokens
Missing table (`relation does not exist`)	Wraps table block in conditional `to_regclass` check

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

Troubleshooting

Problem	Fix
`FLYWAY_ROOT is not set`	Set `FLYWAY_ROOT` in MCP `env`
`Invalid flag: -configFiles` (Windows)	Upgrade to `@mhdd_24/[email protected]`+
`No Flyway projects found`	Ensure subfolders contain `flyway.toml`
`No Flyway database plugin`	Install the Flyway plugin for that database type
Stale version after publish	Restart MCP; `npx` uses latest unless pinned

More detail: docs/WIKI.md

License

ISC

@mhdd_24/flyway-mcp