Skip to main content
Glama
Sign In
@mhdd_24/flyway-mcp

@mhdd_24/flyway-mcp

by Mhdd-24
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

@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 (always executes scripts; skipExecutingMigrations is forced off)

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

Related MCP server: coalesce-transform-mcp

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/flyway-mcp@1.0.1+

ENOENT rename under C:\Users\…\migrations\…

Upgrade to 1.0.3+ — paths resolve under FLYWAY_ROOT/<project>

History shows execution_time = 0 / missing seed data

Do not use -skipExecutingMigrations=true. Upgrade MCP to 1.0.4+; delete false history rows and remigrate with real execute

No Flyway projects found

Ensure subfolders contain flyway.toml

No Flyway database plugin

Install the Flyway plugin for that database type

Edited already-applied migration does nothing

Expected — add a new version or run SQL manually after repair

Stale version after publish

Restart MCP; npx uses latest unless pinned

More detail: docs/WIKI.md

License

ISC

Available Tools

3 tools
dev_flyway_migrationB

Dev Flyway Migration: run flyway repair and migrate for all configured projects against the Development environment. Use when the user says "Dev Flyway Migration". Automatically fixes duplicate versions, checksum mismatches, Flyway placeholder errors in JS migrations, and missing-table failures where possible.

Inputs: projects.

list_flyway_projectsB

List Flyway projects discovered under FLYWAY_ROOT with QA/Dev config availability.

Inputs: no named parameters.

qa_flyway_migrationA

QA Flyway Migration: run flyway repair and migrate for all configured projects against the QA environment. Use when the user says "QA Flyway Migration". Automatically fixes duplicate versions, checksum mismatches, Flyway placeholder errors in JS migrations, and missing-table failures where possible.

Inputs: projects.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing projects versus running migrations against QA or Dev. The QA and Dev migration tools are only differentiated by environment, which is explicitly named in both the tool name and description, so misselection is unlikely.

    Naming Consistency4/5

    All tools use snake_case and follow a predictable semantic pattern. The only minor deviation is that one tool leads with an action verb (list_) while the others lead with an environment qualifier (qa_/dev_), but the pattern remains readable and consistent.

    Tool Count5/5

    Three tools is well-scoped for a Flyway migration helper focused on discovery and two environment-specific operations. Each tool earns its place without redundancy.

    Completeness3/5

    The surface covers listing projects and migrating QA/Dev, but lacks notable lifecycle operations such as per-project targeting, status/validate, rollback/undo, and any production environment path. Agents can work around some gaps, but key migration management operations are missing.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers