# Supabase MCP Server Setup Guide

> **Scope:** nextjs-supabase
> **Layer:** 2 (on keyword)
> **Keywords:** supabase, mcp, setup, model context protocol
> **Load When:** supabase mcp setup keywords detected

Direct database management from Claude Code via Model Context Protocol

## What It Provides

The Supabase MCP Server lets Claude Code interact directly with your Supabase project's database. This enables:

- Running SQL queries and viewing results
- Creating and managing database migrations
- Inspecting table schemas, indexes, and RLS policies
- Managing Supabase Auth, Storage, and Edge Functions
- Schema diffing and migration generation

## CRITICAL WARNING

```
==========================================================
  NEVER connect to a PRODUCTION Supabase project via MCP.

  MCP provides direct database access. A single bad query
  can DROP tables, DELETE data, or DISABLE RLS.

  ONLY connect to:
  - Local Supabase (supabase start)
  - Development/staging projects
  - Disposable test projects
==========================================================
```

## Setup

### 1. Get Your Supabase Connection Details

From your Supabase Dashboard > Project Settings > API:
- **Project URL**: `https://xxxxxxxxxxxx.supabase.co`
- **Service Role Key**: `eyJhbGc...` (Settings > API > service_role key)

For local Supabase (`supabase start`):
- **Project URL**: `http://127.0.0.1:54321`
- **Service Role Key**: Output from `supabase status`

### 2. Configure Claude Desktop / Claude Code

Add the Supabase MCP server to your configuration.

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://xxxxxxxxxxxx.supabase.co",
        "--supabase-service-role-key",
        "eyJhbGc...",
        "--read-only"
      ]
    }
  }
}
```

**Claude Code** (`.claude/settings.local.json`):

```json
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "https://xxxxxxxxxxxx.supabase.co",
        "--supabase-service-role-key",
        "eyJhbGc...",
        "--read-only"
      ]
    }
  }
}
```

### 3. Default: Read-Only Mode

The `--read-only` flag is included by default. In this mode:

| Operation | Allowed |
|-----------|---------|
| SELECT queries | Yes |
| DESCRIBE / schema inspection | Yes |
| LIST tables, policies, indexes | Yes |
| INSERT / UPDATE / DELETE | No |
| CREATE / ALTER / DROP | No |
| Migration creation | No |

To enable write access (development only), remove `--read-only`:

```json
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--supabase-url",
        "http://127.0.0.1:54321",
        "--supabase-service-role-key",
        "your-local-service-role-key"
      ]
    }
  }
}
```

Write mode should ONLY be used with local Supabase or disposable dev projects.

## Available Tool Groups

The Supabase MCP Server exposes these tool groups:

### Database Tools

| Tool | Description |
|------|-------------|
| `list_tables` | List all tables in the project |
| `list_extensions` | List installed PostgreSQL extensions |
| `list_migrations` | List applied migrations |
| `apply_migration` | Apply a new SQL migration |
| `execute_sql` | Run arbitrary SQL (read-only by default) |
| `get_migration_status` | Check pending vs applied migrations |

### Auth Tools

| Tool | Description |
|------|-------------|
| `get_auth_config` | View auth provider configuration |
| `list_auth_users` | List authenticated users |

### Storage Tools

| Tool | Description |
|------|-------------|
| `list_storage_buckets` | List storage buckets |
| `get_storage_config` | View storage configuration |

### Project Tools

| Tool | Description |
|------|-------------|
| `get_project_config` | View project settings |
| `get_project_api_keys` | View API keys |

## Usage for Migrations and Schema Management

### Inspecting Current Schema

Ask Claude Code to use the MCP tools:

```
"Show me all tables and their RLS policies"
"What indexes exist on the documents table?"
"List all migrations applied so far"
```

### Creating Migrations

With write mode enabled on a local/dev project:

```
"Create a migration to add a 'tags' column to the documents table"
"Add an RLS policy so only tenant admins can delete documents"
"Enable the pgvector extension and create the embedding column"
```

The MCP server will generate and apply SQL migrations through Supabase's migration system.

### Schema Diffing

```
"Compare the current schema against the migration files"
"Show me what would change if I apply the pending migration"
```

## Usage with MORPH-SPEC Workflow

During MORPH-SPEC phases, the MCP server is useful for:

| Phase | MCP Usage |
|-------|-----------|
| **Phase 2 (Design)** | Inspect existing schema to inform spec |
| **Phase 4 (Tasks)** | Verify migration dependencies |
| **Phase 5 (Implement)** | Apply migrations, verify RLS policies, test queries |

### Example Workflow

```
1. Design phase: "List current tables and extensions"
2. Write migration SQL in supabase/migrations/
3. Apply via MCP: "Apply migration 003_add_search_logs.sql"
4. Verify: "Show RLS policies on search_logs table"
5. Test: "Run SELECT * FROM search_logs LIMIT 5"
```

## Security Best Practices

1. **Always use `--read-only` unless actively running migrations**
2. **Never store service_role keys in version control** -- use environment variables or a secrets manager
3. **Use local Supabase for development** (`supabase start`) instead of cloud projects
4. **Rotate keys if accidentally exposed** -- Supabase Dashboard > Settings > API > Regenerate
5. **Restrict MCP to development machines only** -- never configure on CI/CD or shared servers
6. **Review SQL before applying** -- the MCP server executes SQL with service_role privileges, bypassing all RLS

### Environment Variable Alternative

Instead of hardcoding keys in the config file:

```json
{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only"
      ],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}"
      }
    }
  }
}
```

Set the environment variables in your shell profile or `.env` file (never committed).

---

*MORPH-SPEC by Polymorphism Tech*
