Supabase Coolify MCP Server

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.

- 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

- 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

- 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

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

- 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)

npm install -g supabase-coolify-mcp-server

Or use directly with npx (no installation needed):

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

Create a.envfile 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

- Log into your Coolify instance
- Navigate to "Keys & Tokens" > "API tokens"
- Click "Create New Token"
- Select permissions (recommended:for full access)
- Copy the generated token
- Log into your Supabase dashboard
- Go to Settings > API
- Copy theservice_rolekey (keep this secure!)

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

Update application environment variables.

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

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

start_coolify_application/stop_coolify_application/restart_coolify_application

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

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

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" } } }

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

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

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
- Never commit API tokensto version control
- Use environment variablesfor sensitive data
- Restrict API token permissionsto minimum required
- Rotate tokens regularly
- Use service role keyonly on secure servers
- Enable JWT verificationfor edge functions
- Validate all inputs(automatic with Zod schemas)
- Verify setupbefore production deployments
- Set appropriate file permissionson configuration files:

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

# Run type checking npm run typecheck # Run linter npm run lint # Build project npm run build

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"

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

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:

- ✅.envfile existence and configuration
- ✅ Required environment variables
- ✅ Coolify API connection and authentication
- ✅ Supabase connection and authentication
- ✅ All Supabase services health
- ✅ Network connectivity

🟢 ALL CHECKS PASSED - MCP Server should work correctly ✅ Passed: 10 ❌ Failed: 0 ⚠️ Warnings: 0

Fix:cp env.example .envthen edit with your credentials

❌ ENV: COOLIFY_API_TOKEN: Contains placeholder value

Fix: Replaceyour-coolify-api-token-herewith actual token from Coolify Dashboard → Keys & Tokens

❌ Supabase Authentication: Invalid service role key