🐳 Supabase MCP HTTP Stream Server for n8n
One-Click Docker deployment of Supabase MCP Server with native HTTP Stream Transport support for n8n, AI Agents, and modern automation workflows.
🚀 Quick Start
🌊 Coolify Deployment (Production)
For production deployment on Coolify, follow these detailed steps:
Step 1: Create Resource in Coolify
- Navigate to your Coolify dashboard
- Go to Projects → Select your project (e.g., "My first project")
- Click "Add Resource" → "Docker Compose"
- Choose "From GIT Repository" or "Raw Docker Compose"
Step 2: Configure Docker Compose
Option A: From GIT Repository
- Repository:
https://github.com/BIFROTEK-com/supabase-mcp-http-stream-n8n.git - Branch:
main - Docker Compose Location:
docker/docker-compose.coolify.yaml
Option B: Raw Docker Compose
Copy the content from docker/docker-compose.coolify.yaml
Step 3: Set Environment Variables
Configure these required environment variables in Coolify:
# 🔐 Required: Supabase Configuration
SUPABASE_ACCESS_TOKEN=sbp_your_access_token_here
SUPABASE_PROJECT_REF=your_project_ref_here
# 🔑 Security: API Keys (highly recommended)
MCP_API_KEYS=your-secure-api-key-here
# 📍 Domain Configuration
DOMAIN=your.domain.com
# ⚙️ Optional: Feature Configuration
MCP_FEATURES=database,docs,development,functions
MCP_READ_ONLY=false
MCP_PORT=3333
NODE_ENV=production
# 🛡️ Optional: Security Settings
MCP_RATE_LIMIT_REQUESTS=100
MCP_RATE_LIMIT_GENERAL=60
MCP_ALLOWED_ORIGINS=*
NODE_LOG_LEVEL=warn
Step 4: Configure Domain & Traefik
- Resource Name:
supabase-mcp(or your preferred name) - Domain Configuration:
https://your.domain.com:3333- ✅ Format:
https://your-domain.com:3333 - ✅ Port: Must be
3333(the container port) - ✅ Protocol: Use
httpsfor SSL termination via Traefik
- ✅ Format:
Step 5: Deploy
- Save Configuration
- Click "Deploy"
- Monitor Logs for successful startup:
✅ MCP HTTP Server running on port 3333 🚀 Streamable HTTP: POST /mcp 🌊 SSE: GET/POST /sse ❤️ Health: GET /health 🏠 Landing: GET / 🔗 Ready for connections!
Step 6: Verify Deployment
Test your deployed instance using the API Examples below.
🐳 Local Development
- Clone the repository:
git clone https://github.com/BIFROTEK-com/supabase-mcp-http-stream-n8n.git
cd supabase-mcp-http-stream-n8n
- Create
.envfile:
cp env.example .env
# Edit .env with your Supabase credentials
- Start the server:
cd docker && docker-compose up -d
- Test the connection: See API Examples below
🔌 API Endpoints
🚀 HTTP Stream Transport (Recommended)
The modern MCP transport using HTTP streaming for real-time communication:
| Endpoint | Method | Description |
|---|---|---|
POST /mcp | POST | Main MCP API - HTTP Stream Transport |
GET /health | GET | Health Check - Server status |
GET / | GET | API Dashboard - Landing page (requires API key) |
DELETE /mcp | DELETE | Session Termination - Terminate MCP session |
Example Usage:
curl -X POST https://your-domain.com:3333/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "X-API-Key: your-api-key" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
🌊 SSE Transport (n8n Compatible)
Server-Sent Events transport for legacy n8n MCP Client Tool Node compatibility:
| Endpoint | Method | Description |
|---|---|---|
GET /sse | GET | SSE Connection - Establish Server-Sent Events stream |
POST /messages | POST | SSE Messages - Send JSON-RPC messages via SSE |
SSE Features:
- ✅ Auto Session Management - Secure crypto-based session IDs
- ✅ Keep-Alive Pings - 15-second intervals for connection stability
- ✅ n8n Compatibility - Works with n8n MCP Client Tool Node
- ✅ Automatic Cleanup - Sessions auto-terminate on disconnect
SSE Connection Flow:
- Connect:
GET /sseestablishes SSE stream - Receive: Server sends
endpointevent with sessionId - Send Messages:
POST /messages?sessionId=<session> - Keep-Alive: Server pings every 15 seconds
- Disconnect: Automatic cleanup on connection close
Example Usage:
# 1. Establish SSE connection
curl -N -H "Accept: text/event-stream" https://your-domain.com:3333/sse
# Server responds:
# event: endpoint
# data: /messages?sessionId=abc123...
# data: {"type":"ready","status":"connected","session":"abc123..."}
# 2. Send messages via returned sessionId
curl -X POST https://your-domain.com:3333/messages?sessionId=abc123... \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
🛡️ Security Features
- ✅ API Key Authentication: Secure access control
- ✅ Rate Limiting: DoS protection (configurable)
- ✅ CORS Protection: Configurable origin restrictions
- ✅ Security Headers: Helmet.js with CSP
- ✅ Input Validation: JSON-RPC 2.0 validation
- ✅ SSL/TLS: HTTPS support via Traefik
📊 MCP Tools Available
| Tool | Description |
|---|---|
list_tables | Lists all database tables |
list_extensions | Lists database extensions |
execute_sql | Execute raw SQL queries |
apply_migration | Apply database migrations |
search_docs | Search Supabase documentation |
list_edge_functions | List Edge Functions |
deploy_edge_function | Deploy Edge Functions |
get_project_url | Get project API URL |
get_anon_key | Get anonymous API key |
generate_typescript_types | Generate TypeScript types |
list_migrations | List database migrations |
🔧 Configuration
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
SUPABASE_ACCESS_TOKEN | ✅ | - | Supabase Management API token |
SUPABASE_PROJECT_REF | ✅ | - | Your Supabase project reference |
MCP_API_KEYS | ⚠️ | - | Comma-separated API keys |
MCP_PORT | ❌ | 3333 | HTTP server port |
MCP_FEATURES | ❌ | database,docs,development,functions | Enabled features |
MCP_READ_ONLY | ❌ | false | Read-only mode |
MCP_RATE_LIMIT_REQUESTS | ❌ | 100 | Requests per 15 minutes |
MCP_RATE_LIMIT_GENERAL | ❌ | 60 | Requests per minute |
MCP_ALLOWED_ORIGINS | ❌ | * | CORS allowed origins |
Feature Groups
Enable specific features by setting MCP_FEATURES:
database- Database operations (tables, SQL, migrations)docs- Supabase documentation searchdevelopment- Development tools and utilitiesfunctions- Edge Functions managementaccount- Account management (requires no project scoping)branching- Database branching operationsstorage- Storage managementdebug- Debugging tools
🔄 n8n Integration
⚠️ Important: Built-in MCP Node Issues
The built-in n8n MCP Client node has known issues with SSE Stream Transport (Deprecated) and may not work reliably with this server. For the best experience, we strongly recommend using the community-developed MCP Client node instead.
🌟 Recommended: Community MCP Node
Use the community node: @nerding-io/n8n-nodes-mcp
This community node provides:
- ✅ Full HTTP Stream Transport support (recommended)
- ✅ Reliable SSE Transport for legacy compatibility
- ✅ Better error handling and connection stability
- ✅ Active maintenance and community support
- ✅ AI Agent integration as a tool
📦 Installation
-
Install the community node in your n8n instance:
# Via n8n UI: Settings → Community Nodes → Install # Package name: @nerding-io/n8n-nodes-mcp # Or via Docker environment: N8N_COMMUNITY_PACKAGES_ENABLED=true -
Enable community nodes as tools (for AI Agents):
# Required for using MCP Client as AI Agent tool N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
🚀 Configuration with HTTP Stream Transport
Recommended Setup:
-
Create HTTP Streamable Credentials:
- Base URL:
https://your.domain.com:3333/mcp - API Key: Your configured API key
- Transport:
HTTP Streamable
- Base URL:
-
Add MCP Client Node:
- Connection Type:
HTTP Streamable - Operation:
List Tools/Execute Tool - Select your credentials
- Connection Type:
-
Example Tool Execution:
{ "tool": "list_tables", "parameters": {} }
🌊 Legacy SSE Configuration (if needed)
Only if HTTP Stream doesn't work:
-
Create SSE Credentials:
- SSE URL:
https://your.domain.com:3333/sse - Connection Type:
Server-Sent Events (SSE) - Headers:
X-API-Key: your-api-key
- SSE URL:
-
Configure Node:
- Connection Type:
Server-Sent Events (SSE) - Select your SSE credentials
- Connection Type:
Note: SSE is deprecated but maintained for compatibility. Always try HTTP Stream first.
🤖 AI Agent Integration
The community MCP node works perfectly as an AI Agent tool:
// Example AI Agent prompt
I need you to help me analyze my Supabase database.
First, list all available tables using the list_tables tool.
Then, execute some SQL queries to get insights about the data.
Docker Configuration for AI Agents:
version: '3'
services:
n8n:
image: n8nio/n8n
environment:
- N8N_COMMUNITY_PACKAGES_ENABLED=true
- N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true
- MCP_API_KEY=your-supabase-mcp-api-key
# ... rest of configuration
🎯 Use Cases
- Database Management: Query and manage Supabase databases
- AI Agents: Provide database access to AI assistants
- Automation: Integrate with n8n workflows
- Documentation: Search Supabase docs programmatically
- Edge Functions: Deploy and manage serverless functions
- Data Analysis: Execute complex SQL queries
- Schema Management: Handle database migrations
🔗 Related Projects
- MCP Framework - Model Context Protocol
- Supabase - Open source Firebase alternative
- n8n - Workflow automation platform
- Coolify - Self-hosted Heroku alternative
📝 License
MIT License - see LICENSE file for details.
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
🆘 Support
- GitHub Issues: Report bugs or request features
- Documentation: MCP Framework Docs
- Supabase: Official Documentation
Made with ❤️ by BIFROTEK