Content
# Supabase Management MCP Server
> **Supabase MCP Server** — MCP (Model Context Protocol) tools for managing your self-hosted Supabase instance.
>
> Combines Edge Function CRUD, migration management, log monitoring, and Studio MCP proxy into a single endpoint.
> Vibe Coded.
[](LICENSE)
[](package.json)
[](package.json)
---
## 🚀 Features
| Category | Tool Count | Description |
|----------|-----------|-------------|
| **Edge Functions** | 6 | CRUD + deploy (list, view, create, update, delete, restart) |
| **Migrations** | 4 | SQL migration management (list, view, apply, raw SQL execute) |
| **Logs** | 2 | Docker container logs (edge runtime + any container) |
| **Studio Proxy** | ~11 | Proxies Supabase Studio's built-in MCP tools |
**Total: 12 management + ~11 Studio = ~23 tools** on a single MCP endpoint!
---
## 📦 Quick Start
### 1. Clone & Build
```bash
git clone https://github.com/ubeydtalha/supabase-mgmt-mcp.git
cd supabase-mgmt-mcp
cp .env.example .env
# Fill in your Supabase credentials in .env
npm install
npm run build
```
### 2. Run
```bash
# Directly with Node.js
npm start
# With Docker
docker compose up -d
```
### 3. Connect to VS Code
Add to `~/.vscode/mcp.json` in VS Code:
```json
{
"servers": {
"supabase-mgmt": {
"type": "url",
"url": "http://localhost:3200/mcp",
"headers": {
"apikey": "supabase_mgmt_api_key_here",
"MCP-Protocol-Version": "2025-06-18"
}
}
}
}
```
---
## 🛠️ Tool Reference
### Edge Functions
| Tool | Description |
|------|-------------|
| `supabase_mgmt_list_functions` | List all edge functions |
| `supabase_mgmt_get_function` | Show function source code and details |
| `supabase_mgmt_create_function` | Create a new edge function |
| `supabase_mgmt_update_function` | Update function source code / JWT settings |
| `supabase_mgmt_delete_function` | Delete a function (`confirm: true` required) |
| `supabase_mgmt_deploy` | Restart edge runtime (activate changes) |
### Migrations & SQL
| Tool | Description |
|------|-------------|
| `supabase_mgmt_list_migrations` | List migration files |
| `supabase_mgmt_get_migration` | View migration SQL content |
| `supabase_mgmt_apply_migration` | Apply a migration file |
| `supabase_mgmt_run_sql` | Execute raw SQL |
### Logs
| Tool | Description |
|------|-------------|
| `supabase_mgmt_get_logs` | Fetch edge runtime logs |
| `supabase_mgmt_get_container_logs` | Fetch logs from any Docker container |
### Studio Proxy (optional, enabled when STUDIO_MCP_URL is set)
| Tool | Description |
|------|-------------|
| `list_tables` | List database tables |
| `list_extensions` | List extensions |
| `execute_sql` | Execute SQL queries |
| `apply_migration` | Apply a migration |
| `get_logs` | Get Supabase service logs |
| `search_docs` | Search Supabase documentation |
| `get_advisors` | Get performance/security advice |
| `get_project_url` | Show project URL |
| `get_publishable_keys` | Show API keys |
| `generate_typescript_types` | Generate TypeScript type definitions |
| `list_migrations` | List migrations |
---
## 🔧 Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PORT` | No | `3200` | Server port |
| `SUPABASE_URL` | **Yes** | — | Supabase project URL (e.g. `https://supabase.example.com`) |
| `SUPABASE_SERVICE_ROLE_KEY` | **Yes** | — | Service role key (for admin operations) |
| `SUPABASE_MGMT_API_KEY` | **Yes** | — | API key to connect to the MCP server |
| `SUPABASE_MGMT_API_KEYS` | No | — | Additional API keys (comma-separated) |
| `FUNCTIONS_PATH` | No | `/functions` | Path to edge function files |
| `MIGRATIONS_PATH` | No | `/migrations` | Path to migration SQL files |
| `EDGE_CONTAINER_NAME` | No | `supabase-functions` | Edge runtime Docker container name |
| `STUDIO_MCP_URL` | No | — | Enables Studio MCP proxy |
---
## 🐳 Docker Deployment
### Integration with Self-hosted Supabase
```yaml
# docker-compose.yml (add to your stack)
services:
supabase-mgmt-mcp:
image: ghcr.io/ubeydtalha/supabase-mgmt-mcp:latest
container_name: supabase-mgmt-mcp
restart: unless-stopped
ports:
- "3200:3200"
env_file: .env
volumes:
- /path/to/functions:/functions
- /path/to/migrations:/migrations
- /var/run/docker.sock:/var/run/docker.sock:ro
networks:
- supabase
```
### With Kong API Gateway
```yaml
# Add to Kong declarative config
services:
- name: supabase-mgmt-mcp
url: http://supabase-mgmt-mcp:3200/mcp
routes:
- name: mcp
strip_path: false
paths:
- /mcp
```
---
## ⚠️ Important Notes
1. **Session Management**: MCP StreamableHTTP transport expects a **new session** for each `tools/call`. VS Code Copilot handles this automatically.
2. **exec_sql Prerequisite**: The `exec_sql` function must exist in PostgreSQL for `apply_migration` and `run_sql` tools:
```sql
CREATE OR REPLACE FUNCTION public.exec_sql(sql_text text)
RETURNS void LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
BEGIN EXECUTE sql_text; END; $$;
GRANT EXECUTE ON FUNCTION public.exec_sql(text) TO anon, authenticated, service_role;
```
3. **Docker Socket**: `/var/run/docker.sock` must be mounted for container logs and edge runtime restart.
4. **Activating Changes**: After creating/updating/deleting functions, run `supabase_mgmt_deploy` to apply changes.
---
## 📚 Documentation
- [Setup Guide](docs/SETUP.md) — Detailed setup instructions
- [Architecture](docs/ARCHITECTURE.md) — System architecture and design decisions
- [Usage Examples](docs/USAGE.md) — Copilot Chat usage scenarios
---
## 📄 License
MIT License — see [LICENSE](LICENSE).
---
## 🤝 Contributing
PRs and issues are welcome. Please open an issue first for major changes.
