# 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: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-22+-green)](package.json)
[![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.27+-blue)](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.