Supabase Coolify MCP Server

⚡ One-Click Install

Install directly in your favorite AI coding tool:

Claude Code:

claude mcp add supabase-coolify -- npx -y supabase-coolify-mcp-server

> Note: After installation, you'll need to configure the required environment variables. See Configuration below.

A comprehensive TypeScript MCP (Model Context Protocol) server for managing self-hosted Supabase on Coolify. This server enables AI agents to fully deploy migrations, push edge functions, configure services, and manage Supabase deployments with ease.

**📦 NPM Package • 📚 Documentation • 🚀 Quick Start**

🚀 Features

Supabase Management

• Database Migrations: Deploy, track, rollback, and manage database migrations
• Migration Rollback: Safely rollback migrations with down SQL support
• Supabase CLI Integration: Full CLI integration for local development and deployment
• Edge Functions: Deploy, invoke, monitor, and delete edge functions
• Storage Management: Create and manage storage buckets
• Auth Configuration: Configure authentication providers and settings
• Realtime Configuration: Manage realtime service settings
• Health Monitoring: Check status of all Supabase services
• Type Generation: Generate TypeScript types from database schema

Production Features

• Input Validation: Zod-based validation for all tool inputs
• Health Checks: Automatic startup checks and verification tool
• Error Handling: Comprehensive error messages with troubleshooting hints
• Type Safety: Full TypeScript support throughout

Coolify Integration

• Application Management: List, deploy, start, stop, and restart applications
• Service Management: Control Coolify services
• Database Management: Manage Coolify-hosted databases
• Environment Variables: Update application configuration securely
• Logs: Access application logs for debugging

Deployment Automation

• One-Click Deployment: Deploy complete Supabase instances on Coolify
• Configuration Management: Update deployment settings dynamically
• Status Monitoring: Track deployment health and status

📋 Prerequisites

• Node.js >= 18.0.0
• A Coolify instance (self-hosted or cloud)
• Coolify API token with appropriate permissions
• A self-hosted Supabase instance (or ready to deploy one)

🔧 Installation

Method 1: NPM (Recommended)

Install globally via NPM:

npm install -g supabase-coolify-mcp-server

Or use directly with npx (no installation needed):

npx supabase-coolify-mcp-server

Package: https://www.npmjs.com/package/supabase-coolify-mcp-server

Method 2: From Source

Clone and build from GitHub:

git clone https://github.com/dj-pearson/supabase-coolify-mcp-server.git
cd supabase-coolify-mcp-server
npm install
npm run build

⚙️ Configuration

Environment Variables

Create a `.env` file or set the following environment variables:

# Required: Coolify Configuration
COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-coolify-api-token-here

# Required: Supabase Configuration
SUPABASE_URL=https://your-supabase-instance.example.com
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

# Optional: Coolify Team
COOLIFY_TEAM_ID=optional-team-id

# Optional: Supabase Additional Config
SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_PROJECT_ID=your-project-id
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_FUNCTIONS_URL=https://your-supabase-instance.example.com/functions/v1

# Optional: Direct Database Access
SUPABASE_DB_HOST=localhost
SUPABASE_DB_PORT=5432
SUPABASE_DB_NAME=postgres
SUPABASE_DB_USER=postgres
SUPABASE_DB_PASSWORD=your-db-password

Getting API Tokens

Coolify API Token

1. Log into your Coolify instance

2. Navigate to "Keys & Tokens" > "API tokens"

3. Click "Create New Token"

4. Select permissions (recommended: `*` for full access)

5. Copy the generated token

Supabase Service Role Key

For self-hosted Supabase:

1. Log into your Supabase dashboard

2. Go to Settings > API

3. Copy the `service_role` key (keep this secure!)

Or from your Supabase deployment environment variables:

echo $SERVICE_ROLE_KEY

🎯 Usage

⚠️ IMPORTANT: Environment Variables Required

The MCP server requires environment variables to connect to Coolify and Supabase.

Recommended Setup (Works for Everyone):

Add environment variables directly to your MCP configuration:

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "npx",
      "args": ["-y", "supabase-coolify-mcp-server"],
      "env": {
        "COOLIFY_API_URL": "http://your-coolify-url:8000",
        "COOLIFY_API_TOKEN": "your-actual-token",
        "SUPABASE_URL": "https://your-supabase-url.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-actual-service-role-key"
      }
    }
  }
}

Replace the placeholder values with your actual credentials!

📖 Configuration Options

The server supports three methods for providing environment variables (in priority order):

1. MCP Config `env` section ⭐ RECOMMENDED - Works for everyone, self-contained

2. System environment variables - For advanced users who want credentials outside config

3. `.env` file with wrapper script - For local development only (not scalable)

For detailed setup instructions for each method, see: MCP_CONFIGURATION.md

Common Mistake: ❌ Leaving placeholder values like `https://your-supabase-instance.example.com`

Solution: ✅ Replace ALL placeholders with your actual URLs and credentials!

With Claude Desktop

Add to your Claude Desktop configuration:

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Windows: `%APPDATA%/Claude/claude_desktop_config.json`

Using NPX (Recommended - Always Latest)

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "npx",
      "args": ["-y", "supabase-coolify-mcp-server"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-coolify-api-token",
        "SUPABASE_URL": "https://your-supabase-instance.example.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Using Global Installation

First install globally:

npm install -g supabase-coolify-mcp-server

Then configure:

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "supabase-coolify-mcp",
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-coolify-api-token",
        "SUPABASE_URL": "https://your-supabase-instance.example.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

Development Mode

# Using environment variables
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-token"
export SUPABASE_URL="https://your-instance.example.com"
export SUPABASE_SERVICE_ROLE_KEY="your-key"

npm run dev

# Or with .env file
npm run dev

Running Built Version

npm run build
npm start

🛠️ Available Tools

Database Migration Tools

`list_migrations`

List all database migrations with their status.

// No parameters required

`deploy_migration`

Deploy a new database migration.

{
  "sql": "CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT);",
  "name": "create_users_table"
}

`execute_sql`

Execute raw SQL query on the Supabase database.

{
  "sql": "SELECT * FROM users LIMIT 10;"
}

`get_migration_status`

Get status of a specific migration.

{
  "version": "20231201120000"
}

Edge Functions Tools

`list_edge_functions`

List all deployed edge functions.

`deploy_edge_function`

Deploy a new edge function.

{
  "name": "hello-world",
  "code": "export default function handler(req) { return new Response('Hello World'); }",
  "verify_jwt": true
}

`delete_edge_function`

Delete an edge function.

{
  "name": "hello-world"
}

`get_edge_function_logs`

Get logs for an edge function.

{
  "name": "hello-world",
  "limit": 100
}

`invoke_edge_function`

Invoke an edge function.

{
  "name": "hello-world",
  "payload": { "key": "value" }
}

Storage Tools

`list_storage_buckets`

List all storage buckets.

`create_storage_bucket`

Create a new storage bucket.

{
  "id": "avatars",
  "public": true,
  "file_size_limit": 5242880
}

`delete_storage_bucket`

Delete a storage bucket.

{
  "id": "avatars"
}

Auth & Configuration Tools

`get_auth_config`

Get authentication configuration.

`update_auth_config`

Update authentication configuration.

{
  "config": {
    "site_url": "https://myapp.com",
    "enable_signup": true
  }
}

`check_supabase_health`

Check health of all Supabase services.

`get_supabase_version`

Get Supabase version information.

`verify_setup` ⭐

Verify system setup and check health of all services (Coolify, Supabase, CLI).

This comprehensive tool checks:

• Coolify connection and authentication
• Supabase connection and authentication
• Database accessibility
• CLI availability
• Response times and service status

Returns: Detailed health report with recommendations for any issues found.

See docs/VERIFICATION.md for complete verification guide.

Coolify Management Tools

`list_coolify_applications`

List all Coolify applications.

`get_coolify_application`

Get details of a specific application.

{
  "uuid": "app-uuid-here"
}

`update_coolify_application_env`

Update application environment variables.

{
  "uuid": "app-uuid-here",
  "env": {
    "NODE_ENV": "production",
    "API_KEY": "secret"
  }
}

`deploy_coolify_application`

Deploy a Coolify application.

{
  "uuid": "app-uuid-here"
}

`start_coolify_application` / `stop_coolify_application` / `restart_coolify_application`

Control application lifecycle.

{
  "uuid": "app-uuid-here"
}

`get_coolify_logs`

Get application logs.

{
  "uuid": "app-uuid-here",
  "lines": 100
}

Deployment Tools

`deploy_supabase_to_coolify`

Deploy a complete Supabase instance on Coolify.

{
  "name": "my-supabase",
  "config": {
    "postgres_version": "15",
    "enable_realtime": true,
    "enable_storage": true,
    "enable_auth": true,
    "custom_domain": "https://supabase.myapp.com",
    "environment_variables": {
      "CUSTOM_VAR": "value"
    }
  }
}

`update_supabase_deployment`

Update an existing Supabase deployment.

{
  "uuid": "app-uuid-here",
  "config": {
    "enable_graphql": true
  }
}

`get_deployment_status`

Get status of a Supabase deployment.

{
  "uuid": "app-uuid-here"
}

📚 MCP Resources

The server exposes these resources for MCP clients:

• `supabase://migrations` - All database migrations
• `supabase://edge-functions` - All edge functions
• `supabase://storage-buckets` - All storage buckets
• `supabase://auth-config` - Authentication configuration
• `supabase://health` - Service health status
• `coolify://applications` - All Coolify applications
• `coolify://services` - All Coolify services
• `coolify://databases` - All Coolify databases

🔒 Security Best Practices

1. Never commit API tokens to version control

2. Use environment variables for sensitive data

3. Restrict API token permissions to minimum required

4. Rotate tokens regularly

5. Use service role key only on secure servers

6. Enable JWT verification for edge functions

7. Validate all inputs (automatic with Zod schemas)

8. Verify setup before production deployments

9. Set appropriate file permissions on configuration files:

chmod 600 ~/.env
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

🧪 Testing & Verification

Build and Type Check

# Run type checking
npm run typecheck

# Run linter
npm run lint

# Build project
npm run build

Verify Setup

After starting the server, verify everything is working:

# Start the server
npm start

# Then ask Claude:
"Run verify_setup to check if everything is configured correctly"

See docs/VERIFICATION.md for complete verification guide.

🔍 Diagnostics & Testing

Before reporting issues or if you're having connection problems, use the built-in diagnostic tool:

Quick Diagnosis

Run the automated diagnostic tool to check your setup:

# Using npm
npm run diagnose

# Or on Windows
.\diagnose.ps1

# Or on Linux/Mac
./diagnose.sh

The diagnostic tool will automatically check:

• ✅ `.env` file existence and configuration
• ✅ Required environment variables
• ✅ Coolify API connection and authentication
• ✅ Supabase connection and authentication
• ✅ All Supabase services health
• ✅ Network connectivity

Expected Output (When Working)

🟢 ALL CHECKS PASSED - MCP Server should work correctly

✅ Passed:   10
❌ Failed:   0
⚠️  Warnings: 0

Common Diagnostic Issues

Missing .env File

❌ .env file NOT found!

Fix: `cp env.example .env` then edit with your credentials

Placeholder Values

❌ ENV: COOLIFY_API_TOKEN: Contains placeholder value

Fix: Replace `your-coolify-api-token-here` with actual token from Coolify Dashboard → Keys & Tokens

Wrong Supabase Key

❌ Supabase Authentication: Invalid service role key

Fix: Make sure you're using the service_role key, NOT the anon key!

Get it from: Supabase Dashboard → Settings → API → `service_role` key

Connection Failed

❌ Coolify Connection: ECONNREFUSED

Fix: Verify Coolify is running and accessible at the configured URL

Getting Credentials

Coolify API Token:

1. Coolify Dashboard → Profile → Keys & Tokens → API Tokens

2. Click "Create New Token"

3. Copy the token (you won't see it again!)

4. Add to `.env` as `COOLIFY_API_TOKEN`

Supabase Service Role Key:

• Supabase Cloud: Dashboard → Settings → API → Copy `service_role` key
• Self-hosted: Check Coolify deployment environment variables for `SERVICE_ROLE_KEY`

Quick Start Guide

For detailed troubleshooting, see:

• **START_HERE.md** - Quick start with diagnostics
• **DIAGNOSE_NOW.md** - Step-by-step diagnosis
• **TROUBLESHOOTING.md** - Comprehensive troubleshooting guide

🐛 Troubleshooting

Common Issues

1. Missing Environment Variables

Error: `Missing required environment variables: COOLIFY_API_URL, COOLIFY_API_TOKEN`

Solution: Ensure all required environment variables are set. Check your `.env` file or Claude Desktop configuration.

2. Connection Failed

Error: `Failed to connect to Coolify API`

Solution:

• Verify Coolify instance is running
• Check API URL is correct (include `http://` or `https://`)
• Ensure API token has proper permissions
• Check network connectivity

3. Authentication Failed

Error: `Unauthorized` or `401`

Solution:

• Verify API tokens are correct
• Check token hasn't expired
• Ensure token has required permissions

4. MCP Server Not Appearing

Solution:

• Restart Claude Desktop
• Check configuration file path is correct for your OS
• Verify JSON syntax in configuration
• Check server logs for errors

Debug Mode

Run with debug output:

DEBUG=* npm start

📖 Example Use Cases

1. Deploy a New Supabase Instance

// Using the MCP tool
deploy_supabase_to_coolify({
  name: "production-supabase",
  config: {
    postgres_version: "15",
    enable_realtime: true,
    enable_storage: true,
    custom_domain: "https://api.myapp.com"
  }
})

2. Deploy Database Migration

deploy_migration({
  name: "add_user_profiles",
  sql: `
    CREATE TABLE user_profiles (
      id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
      user_id UUID REFERENCES auth.users(id),
      display_name TEXT,
      avatar_url TEXT,
      created_at TIMESTAMP DEFAULT NOW()
    );
  `
})

3. Deploy Edge Function

deploy_edge_function({
  name: "send-email",
  code: `
    import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
    
    serve(async (req) => {
      const { to, subject, body } = await req.json()
      // Send email logic here
      return new Response(JSON.stringify({ success: true }))
    })
  `,
  verify_jwt: true
})

4. Monitor Deployment Health

// Check overall health
check_supabase_health()

// Get specific deployment status
get_deployment_status({ uuid: "your-app-uuid" })

// View logs
get_coolify_logs({ uuid: "your-app-uuid", lines: 100 })

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

🔗 Links

• NPM Package: https://www.npmjs.com/package/supabase-coolify-mcp-server
• GitHub Repository: https://github.com/dj-pearson/supabase-coolify-mcp-server
• Coolify: https://coolify.io - Self-hostable Heroku/Netlify alternative
• Supabase: https://supabase.com - Open source Firebase alternative
• Model Context Protocol: https://modelcontextprotocol.io - MCP specification

📞 Support

For issues and questions:

• Create an issue on GitHub
• Check the troubleshooting section
• Review Coolify and Supabase documentation

Note: This MCP server is designed for self-hosted Supabase instances on Coolify. It provides comprehensive management capabilities while maintaining security through environment variables and proper token handling.