migrate-mcp-server

Migrate MCP Server

A Model Context Protocol (MCP) server that provides database migration management capabilities using the golang-migrate/migrate library.

Features

This MCP server exposes the following tools and resources for database migration management:

Tools

• migrate_up - Apply pending database migrations
• migrate_down - Rollback database migrations
• migrate_version - Get current migration version
• migrate_status - Show migration status and pending migrations
• migrate_force - Force set migration version (use with caution)
• migrate_create - Create new migration files
• migrate_drop - Drop database and migration history (destructive)

Resources

• migrate://config - Current migration configuration settings
• migrate://migrations - List of available migration files
• migrate://status - Current migration status and version

Prerequisites

1. golang-migrate binary: Install the migrate CLI tool

   # Install via Go
   go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
   
   # Or via Homebrew (macOS)
   brew install golang-migrate
   
   # Or download from releases
   # https://github.com/golang-migrate/migrate/releases
   

2. Database: A supported database (PostgreSQL, MySQL, SQLite, etc.)

3. Migration files: A directory containing your migration files

Installation

# Clone or create the project
npm install

# Build the project
npm run build

Configuration

Configure the server using environment variables:

• DATABASE_URL - Database connection string (required)
• MIGRATIONS_PATH - Path to migration files directory (default: "./migrations")
• MIGRATE_BINARY - Path to migrate binary (default: "migrate")

Database URL Examples

# PostgreSQL
export DATABASE_URL="postgres://user:password@localhost:5432/dbname?sslmode=disable"

# MySQL
export DATABASE_URL="mysql://user:password@localhost:3306/dbname"

# SQLite
export DATABASE_URL="sqlite3://path/to/database.db"

Usage

Local Development

# Set required environment variables
export DATABASE_URL="postgres://user:password@localhost:5432/dbname?sslmode=disable"
export MIGRATIONS_PATH="./db/migrations"

# Start with stdio transport (for direct MCP client connection)
npm start

# Or start with HTTP transport (for remote connections)
npm run start:http

Using with Claude Desktop (Local)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "migrate": {
      "command": "node",
      "args": ["/path/to/migrate-mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/dbname?sslmode=disable",
        "MIGRATIONS_PATH": "./db/migrations"
      }
    }
  }
}

Kubernetes Deployment

Deploy the MCP server as a container in your Kubernetes cluster for remote access:

Quick Start

# Set your database URL
export DATABASE_URL="postgres://user:password@db-host:5432/dbname?sslmode=disable"

# Deploy everything to Kubernetes
make deploy-local

Manual Deployment Steps

1. Build and prepare:

   make build
   make secret-create DATABASE_URL="your-database-url"
   

2. Deploy to cluster:

   make k8s-deploy
   

3. Access the service:

   # Port forward to access locally
   make k8s-port-forward
   
   # Or check status
   make k8s-status
   

Using with Claude Desktop (Remote)

For remote access via HTTP transport, configure Claude Desktop to connect to your Kubernetes service:

{
  "mcpServers": {
    "migrate": {
      "command": "curl",
      "args": [
        "-X", "POST",
        "-H", "Content-Type: application/json",
        "http://migrate-mcp.example.com/message"
      ],
      "env": {}
    }
  }
}

Container Deployment

Using Docker

# Build image
docker build -t migrate-mcp-server .

# Run container
docker run -d \
  -p 3000:3000 \
  -e DATABASE_URL="postgres://user:password@host:5432/dbname" \
  -e TRANSPORT=http \
  -v ./migrations:/app/migrations:ro \
  migrate-mcp-server

Makefile Commands

# Show all available commands
make help

# Build everything
make build

# Deploy locally (kind/minikube)
make deploy-local

# Deploy to remote cluster
make deploy-remote REGISTRY=your-registry.com

# Check status
make k8s-status

# View logs
make k8s-logs

# Clean up
make k8s-delete

Migration File Structure

Migration files should follow the golang-migrate naming convention:

migrations/
├── 000001_create_users_table.up.sql
├── 000001_create_users_table.down.sql
├── 000002_add_email_index.up.sql
└── 000002_add_email_index.down.sql

Each migration requires both .up.sql and .down.sql files:

000001_create_users_table.up.sql:

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

000001_create_users_table.down.sql:

DROP TABLE users;

Tool Usage Examples

Apply Migrations

Use the migrate_up tool to apply all pending migrations, or specify a number of steps.

Rollback Migrations

Use the migrate_down tool with the number of steps to rollback.

Check Status

Use the migrate_status tool to see current version and available migrations.

Create New Migration

Use the migrate_create tool with a descriptive name like "add_user_preferences_table".

Force Version (Emergency Use)

Use the migrate_force tool to manually set the database version when migrations are in a dirty state.

Security Considerations

• Store database credentials securely
• Validate migration files before applying
• Use the migrate_drop tool with extreme caution
• Consider database backups before running migrations
• Restrict access to migration tools in production

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

Error Handling

The server provides detailed error messages for common issues:

• Missing database URL configuration
• Migration file not found
• Database connection failures
• Migration execution errors
• Dirty database state

Supported Databases

The server supports all databases that golang-migrate supports:

• PostgreSQL
• MySQL/MariaDB
• SQLite
• MongoDB
• Cassandra
• And many others

Database support depends on the golang-migrate binary compilation flags.

License

MIT