MCP server for managing self-hosted Supabase on Coolify with full deployment support
npm install supabase-coolify-mcp-server




Install directly in your favorite AI coding tool:



Claude Code:
``bash`
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
- 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)
Install globally via NPM:
`bash`
npm install -g supabase-coolify-mcp-server
Or use directly with npx (no installation needed):
`bash`
npx supabase-coolify-mcp-server
Package: https://www.npmjs.com/package/supabase-coolify-mcp-server
Clone and build from GitHub:
`bash`
git clone https://github.com/dj-pearson/supabase-coolify-mcp-server.git
cd supabase-coolify-mcp-server
npm install
npm run build
Create a .env file or set the following environment variables:
`envRequired: Coolify Configuration
COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-coolify-api-token-here
$3
#### 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:
`bash
echo $SERVICE_ROLE_KEY
`๐ฏ Usage
$3
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:
`json
{
"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!
---
$3
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!---
$3
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)
`json
{
"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:
`bash
npm install -g supabase-coolify-mcp-server
`Then configure:
`json
{
"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"
}
}
}
}
`$3
`bash
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
`$3
`bash
npm run build
npm start
`๐ ๏ธ Available Tools
$3
####
list_migrations
List all database migrations with their status.`typescript
// No parameters required
`####
deploy_migration
Deploy a new database migration.`typescript
{
"sql": "CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT);",
"name": "create_users_table"
}
`####
execute_sql
Execute raw SQL query on the Supabase database.`typescript
{
"sql": "SELECT * FROM users LIMIT 10;"
}
`####
get_migration_status
Get status of a specific migration.`typescript
{
"version": "20231201120000"
}
`$3
####
list_edge_functions
List all deployed edge functions.####
deploy_edge_function
Deploy a new edge function.`typescript
{
"name": "hello-world",
"code": "export default function handler(req) { return new Response('Hello World'); }",
"verify_jwt": true
}
`####
delete_edge_function
Delete an edge function.`typescript
{
"name": "hello-world"
}
`####
get_edge_function_logs
Get logs for an edge function.`typescript
{
"name": "hello-world",
"limit": 100
}
`####
invoke_edge_function
Invoke an edge function.`typescript
{
"name": "hello-world",
"payload": { "key": "value" }
}
`$3
####
list_storage_buckets
List all storage buckets.####
create_storage_bucket
Create a new storage bucket.`typescript
{
"id": "avatars",
"public": true,
"file_size_limit": 5242880
}
`####
delete_storage_bucket
Delete a storage bucket.`typescript
{
"id": "avatars"
}
`$3
####
get_auth_config
Get authentication configuration.####
update_auth_config
Update authentication configuration.`typescript
{
"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.
$3
####
list_coolify_applications
List all Coolify applications.####
get_coolify_application
Get details of a specific application.`typescript
{
"uuid": "app-uuid-here"
}
`####
update_coolify_application_env
Update application environment variables.`typescript
{
"uuid": "app-uuid-here",
"env": {
"NODE_ENV": "production",
"API_KEY": "secret"
}
}
`####
deploy_coolify_application
Deploy a Coolify application.`typescript
{
"uuid": "app-uuid-here"
}
`####
start_coolify_application / stop_coolify_application / restart_coolify_application
Control application lifecycle.`typescript
{
"uuid": "app-uuid-here"
}
`####
get_coolify_logs
Get application logs.`typescript
{
"uuid": "app-uuid-here",
"lines": 100
}
`$3
####
deploy_supabase_to_coolify
Deploy a complete Supabase instance on Coolify.`typescript
{
"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.`typescript
{
"uuid": "app-uuid-here",
"config": {
"enable_graphql": true
}
}
`####
get_deployment_status
Get status of a Supabase deployment.`typescript
{
"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:
`bash
chmod 600 ~/.env
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
`๐งช Testing & Verification
$3
`bash
Run type checking
npm run typecheckRun linter
npm run lintBuild project
npm run build
`$3
After starting the server, verify everything is working:`bash
Start the server
npm startThen 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:
$3
Run the automated diagnostic tool to check your setup:
`bash
Using npm
npm run diagnoseOr on Windows
.\diagnose.ps1Or 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$3
`
๐ข ALL CHECKS PASSED - MCP Server should work correctlyโ
Passed: 10
โ Failed: 0
โ ๏ธ Warnings: 0
`$3
#### Missing .env File
`bash
โ .env file NOT found!
`
Fix: cp env.example .env then edit with your credentials#### Placeholder Values
`bash
โ 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
`bash
โ 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
`bash
โ Coolify Connection: ECONNREFUSED
`
Fix: Verify Coolify is running and accessible at the configured URL$3
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_TOKENSupabase Service Role Key:
- Supabase Cloud: Dashboard โ Settings โ API โ Copy
service_role key
- Self-hosted: Check Coolify deployment environment variables for SERVICE_ROLE_KEY$3
For detailed troubleshooting, see:
- START_HERE.md - Quick start with diagnostics
- DIAGNOSE_NOW.md - Step-by-step diagnosis
- TROUBLESHOOTING.md - Comprehensive troubleshooting guide
๐ Troubleshooting
$3
#### 1. Missing Environment Variables
Error:
Missing required environment variables: COOLIFY_API_URL, COOLIFY_API_TOKENSolution: Ensure all required environment variables are set. Check your
.env file or Claude Desktop configuration.#### 2. Connection Failed
Error:
Failed to connect to Coolify APISolution:
- 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 401Solution:
- 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
$3
Run with debug output:
`bash
DEBUG=* npm start
`๐ Example Use Cases
$3
`typescript
// 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"
}
})
`$3
`typescript
deploy_migration({
name: "add_user_profiles",
sql:
})
`$3
`typescript
deploy_edge_function({
name: "send-email",
code: ,
verify_jwt: true
})
`$3
`typescript
// 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 })
``Contributions are welcome! Please feel free to submit a Pull Request.
MIT
- 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
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.