MCP server providing comprehensive Supabase management capabilities for both cloud and self-hosted instances.
- Deploy Supabase to Dokploy in under 10 minutes
- Automatic JWT key generation with correct claims (
role,iss) - Automatic HTTP→HTTPS conversion for public URLs
- Post-deployment validation (auth endpoint, container health)
- Detect broken Dokploy-generated JWT keys
- Automatic key regeneration with correct structure
- Environment variable updates via Dokploy API
- Container restart automation
- Handles all 6 connection string formats
- Docker network auto-detection
- Connection pool monitoring and alerts
- Correct role-based query execution (auth schema access)
- CLI bypass for migrations (direct PostgreSQL)
- Migrate schema and data between any Supabase instances
- Chunked transfer for large datasets (512KB memory buffer)
- 100% data integrity verification (checksums, row counts)
- Progress streaming and resumable operations
- Automated encrypted backups (AES-256)
- Compression support (gzip/zstd)
- S3-compatible storage integration
- Point-in-time recovery
- Configurable retention policies
- Container health monitoring
- Connection pool status tracking
- SSL certificate expiration detection
- Log aggregation from all services
- In-MCP notifications + optional webhooks
- Manage dev/staging/production from one interface
- Schema sync between instances
- Safe deployment promotion workflow
- Isolated environment management
- Node.js 18+ OR Docker
- PostgreSQL (for self-hosted) or Supabase account
- Optional: Dokploy instance for automated deployments
Install from npm:
npm install -g supabase-mcp-serverConfigure Claude Desktop (~/Library/Application Support/Claude/config.json):
{
"mcpServers": {
"supabase": {
"command": "supabase-mcp",
"env": {
"DOKPLOY_API_URL": "https://your-dokploy.com",
"DOKPLOY_API_KEY": "your-api-key"
}
}
}
}Recommended for:
- Multi-user teams
- Claude Code integration
- Shared infrastructure management
# 1. Clone and configure
git clone https://github.com/q23/supabase-mcp-server.git
cd supabase-mcp-server
cp .env.example .env
# 2. Generate API key
openssl rand -hex 32 > api-key.txt
nano .env # Add: MCP_API_KEY=<key>, DOKPLOY_API_URL, etc.
# 3. Deploy (auto-detects Docker/PM2/systemd)
chmod +x deployment/deploy.sh
./deployment/deploy.sh
# Server auto-starts on boot
# Auto-restarts on crash
# Health checks every 30s
# Zero downtime updatesDeployment Methods:
- Docker:
restart: always+ health checks + auto-update (Watchtower) - PM2: Cluster mode + auto-restart + memory limits
- systemd: Native Linux service + auto-boot
See Deployment Guide for full details.
- Configure clients: See Client Configuration Guide
Claude Code (~/.config/claude-code/mcp.json):
{
"mcpServers": {
"supabase": {
"url": "http://your-server:3000/mcp",
"transport": "http",
"headers": {
"Authorization": "Bearer your-api-key-here"
}
}
}
}git clone https://github.com/q23/supabase-mcp-server.git
cd supabase-mcp-server
npm install
# HTTP mode (for testing remote clients)
npm run dev:http
# Stdio mode (for local MCP clients)
npm run dev// Use the dokploy_setup_wizard tool in Claude
// Provide: API credentials, domain, project name
// Result: Fully configured Supabase instance in <10 minutes// Use dokploy_validate_config tool
// Detects: Broken JWT keys, HTTP URLs, missing variables
// Offers: One-click regeneration and fix// Use monitor_connections tool
// Shows: Current connections by service
// Alerts: When pool >90% capacity
// Recommends: Pool size adjustments// Use cross_instance_migrate tool
// Migrates: Schema + data with 100% integrity
// Features: Chunked transfer, progress streaming, resume capability// Use create_backup tool
// Creates: Compressed, encrypted backup
// Stores: Local filesystem or S3-compatible storage
// Validates: Integrity with checksums- Client Configuration Guide - Configure Claude Code, Claude Desktop, custom clients
- API Reference - Complete tool reference
- Deployment Guide - Production deployment with SSL, monitoring
- Troubleshooting Guide - Common issues and solutions
- Examples - Usage examples
git clone https://github.com/q23/supabase-mcp-server.git
cd supabase-mcp-server
npm installnpm run dev# Unit tests
npm test
# Integration tests (requires Docker)
docker-compose up -d
npm test -- tests/integration
# Coverage
npm run test:coverage# Check
npm run lint
npm run format:check
# Fix
npm run lint:fix
npm run formatnpm run buildsrc/
├── tools/ # MCP tool implementations
│ ├── dokploy/ # Dokploy integration (P1 critical)
│ ├── core/ # Core database operations
│ ├── migrations/ # Migration management
│ └── backups/ # Backup and restore
├── lib/ # Shared libraries
│ ├── dokploy/ # Dokploy API client
│ ├── postgres/ # PostgreSQL connection management
│ ├── supabase/ # Supabase client wrapper
│ └── memory/ # Memory management (512KB buffer)
└── types/ # TypeScript type definitions
- Dokploy Integration: Native Dokploy support for self-hosted deployments
- Automated Configuration: Deployment with broken config detection
- Security: Encryption, backups, monitoring, audit logs
- Memory Management: 512KB buffer with automatic disk spillover
- Data Integrity: Verified migrations and backups
Contributions are welcome! Please read our Contributing Guide first.
MIT License - see LICENSE file for details
- GitHub Issues: Report a bug
- Documentation: Read the docs
- Discussions: Ask questions
- Phase 1: Project Setup
- Phase 2: Core Foundations
- Phase 3: Zero-Touch Deployment (P1)
- Phase 4: Broken Config Detection (P1)
- Phase 5: Self-Hosted Connection (P1)
- Phase 6: Cross-Instance Migration (P2)
- Phase 7: Production Backups (P2)
- Phase 8: Real-Time Monitoring (P2)
- Phase 9: Multi-Instance Orchestration (P3)
See tasks.md for detailed task breakdown.
Built with ❤️ following the Supabase MCP Constitution