Supabase MCP — Use Cases, Install & Live Demo

Why use it

Key features

Database branching for safe migration testing (Pro plan)
Run SQL directly (read and write)
Generate and apply database migrations
Deploy Edge Functions (Deno) from chat
Inspect logs (postgres, edge-function, auth, realtime)
Read-only mode flag for safer prod use

Live Demo

What it looks like in practice

supabase.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "supabase",
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "supabase": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@supabase/mcp-server-supabase"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add supabase -- npx -y @supabase/mcp-server-supabase

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Supabase

Test a destructive migration on a database branch before applying to prod

👤 Engineers shipping schema changes ⏱ ~30 min advanced

When to use: You have a migration that drops a column or backfills millions of rows, and you want to dry-run on a real-data branch first.

Prerequisites

Supabase Pro plan or higher — Branching is gated to paid plans
Personal access token — supabase.com/dashboard/account/tokens — scope to your org

Flow

Create a branch from prod

Create a database branch named 'test-drop-legacy-col' off the main branch in project <ref>. Wait for it to be ready.✓ Copied

→ Branch created with its own connection string
Run the migration on the branch

Apply the following migration on the new branch: <paste SQL>. Report rows affected and any errors.✓ Copied

→ Migration runs; row counts visible
Verify and either promote or discard

Run sanity SELECTs on the branch (top 10 rows of affected tables, NULL counts on changed columns). If it looks good, tell me and I'll promote; if not, delete the branch.✓ Copied

→ Verification output, then explicit human go/no-go

Outcome: Migration validated against real data shape before it touches prod.

Pitfalls

Branches don't have prod's exact data — they're a snapshot at branch-create time — Note the snapshot timestamp; if your migration is sensitive to recent rows, branch as close to apply time as possible
Branch creation costs compute hours — Always delete the branch after testing; abandoned branches accumulate billing

Combine with: github · postgres

Write and deploy a Supabase Edge Function from chat

👤 Devs adding small backend endpoints (webhooks, signed-URL minters, etc.) ⏱ ~20 min intermediate

When to use: You need a quick HTTP endpoint with DB access — perfect for an Edge Function — and don't want to context-switch to the dashboard.

Flow

Scaffold the function

Create an Edge Function stripe-webhook in project <ref>. It should: validate the Stripe signature, then INSERT a row into table stripe_events. Use Deno-style imports.✓ Copied

→ Function code written with proper Deno conventions
Deploy

Deploy stripe-webhook to project <ref>. Show me the resulting URL.✓ Copied

→ Deployed URL returned
Test with a sample payload

POST a test payload to the URL and tail the function logs. Did it succeed and write a row?✓ Copied

→ Logs show invocation; row visible in table

Outcome: A live endpoint plus a row in the DB to prove it works, in 5 minutes.

Pitfalls

Secrets (STRIPE_SECRET) aren't auto-injected — Set them via the Supabase dashboard or set_secrets MCP tool before invoking; reference via Deno.env.get('STRIPE_SECRET')
Edge functions cold-start; first request is slow — Invoke once after deploy to warm before declaring 'works'

Combine with: stripe · github

Audit Row-Level Security policies on a Supabase project

👤 Security-conscious devs and reviewers ⏱ ~25 min intermediate

When to use: Before launch — you want to confirm RLS is on for every table and the policies actually do what you think.

Flow

List tables and RLS state

List every table in the public schema. For each, is RLS enabled? List the policies attached.✓ Copied

→ Per-table RLS status plus policy bodies
Find tables without RLS

Highlight any table where RLS is OFF, or RLS is ON but no policies exist (effectively deny-all silently).✓ Copied

→ Risk list with clear category for each
Test as anonymous

For 3 sensitive tables, simulate an anon user query (using the anon role). Does it return rows? It shouldn't.✓ Copied

→ Empty results = good; rows returned = policy bug

Outcome: A pre-launch sign-off on auth posture, with evidence per table.

Pitfalls

RLS off on a table you thought was internal — Service-role key bypasses RLS by design — never expose it client-side. Audit which keys are used where

Investigate why a user can't log in

👤 Support engineers, founders doing first-line ⏱ ~10 min beginner

When to use: A user reports 'my login link doesn't work' and you want to see whether the email sent, what auth events fired, etc.

Flow

Find the user

Find the auth user with email '[email protected]'. Show created_at, last_sign_in_at, email_confirmed_at.✓ Copied

→ User record or 'not found' verdict
Check recent auth logs

Pull auth log entries for that user_id in the last 24h. Group by event type.✓ Copied

→ Sequence of auth events (otp_sent, sign_in_failed, etc.)
Resolve

Based on the events, what's the actual problem? Suggest the fix (resend invite, manually confirm, reset password).✓ Copied

→ Diagnosis plus action plan

Outcome: A resolved support ticket with audit trail, in 5 minutes.

Pitfalls

PII flows into chat logs — Avoid pasting raw user records to chat history that's archived; redact emails when summarizing

Generate TypeScript types from your Supabase schema

👤 Frontend devs using `supabase-js` ⏱ ~10 min beginner

When to use: You changed your DB schema and want client types updated to match.

Flow

Generate types

Generate TypeScript types for the public schema of project <ref>. Save to src/types/database.ts.✓ Copied

→ Types file written
Diff and check usage

Compared to the previous types file (in git), what changed? Are any of the changes breaking for existing call sites in src/?✓ Copied

→ Per-change impact analysis
Open PR

Commit the types update plus any necessary call-site fixes. Open a PR titled 'chore: regen db types YYYY-MM-DD'.✓ Copied

→ PR opened with full diff

Outcome: Types stay in sync with schema; broken callsites caught at PR time, not in production.

Pitfalls

Generated types don't include views unless the view has SECURITY INVOKER set — Add views explicitly or document the gap; supabase-js handles them with from('view_name') regardless

Combine with: github · filesystem

Combinations

Pair with other MCPs for X10 leverage

supabase + github

Open a PR with a migration, deploy to a branch, attach test results to the PR

Open a PR adding the migration in supabase/migrations/. Create a Supabase branch with the migration applied. Comment on the PR with the test results from the branch.✓ Copied

supabase + stripe

Build a Stripe webhook Edge Function that writes events into Supabase

Create an Edge Function that receives Stripe webhooks, validates the signature, and inserts events into a stripe_events table. Set up the webhook endpoint in Stripe to point at it.✓ Copied

supabase + filesystem

Sync local SQL migration files with Supabase project state

Compare /supabase/migrations/ on disk to migrations applied on the project. Apply any missing ones in order.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_projects	none	Discover which projects your token can access	free
get_project / pause_project / restore_project	project_id: str	Inspect or control a project	free
create_branch / list_branches / merge_branch / delete_branch	project_id, name?	Database branching for migration testing (Pro+)	Branch compute hours billed
list_tables	project_id, schemas?: str[]	Schema introspection	free
list_extensions / list_migrations	project_id	DB metadata	free
apply_migration	project_id, name: str, query: str	Apply a tracked migration to the project DB	free
execute_sql	project_id, query: str	Ad-hoc SQL — read or write	free
list_edge_functions / get_edge_function / deploy_edge_function	project_id, function name, code, entrypoint	Manage Deno-based edge functions	Edge function invocations billed
get_logs	project_id, service: 'postgres'\|'auth'\|'edge-function'\|...	Pull recent logs for a service	free
generate_typescript_types	project_id	Regenerate client types after schema changes	free
get_anon_key / get_project_url / get_advisors	project_id	Project metadata; advisors flag security or perf issues	free

Cost & Limits

What this costs to run

API quota: Standard Supabase rate limits per plan
Tokens per call: Schema queries: small. Logs and SQL results: depends on data volume — always set time/row limits
Monetary: MCP free; Supabase project is per-plan ($0 free tier; Pro $25/mo). Branching consumes compute hours.
Tip: Branches are great for testing but expensive when forgotten. Always delete_branch after merging or when discarded.

Security

Permissions, secrets, blast radius

Minimum scopes: personal access token scoped to specific projects when possible

Credential storage: Personal access token in env var SUPABASE_ACCESS_TOKEN

Data egress: All calls to api.supabase.com and your project's regional endpoint

Never grant: service_role key to the agent unless absolutely needed — it bypasses RLS

Personal access tokens have org-wide reach by default — scope to specific projects in the dashboard.
execute_sql can do anything — UPDATE, DROP, GRANT. Use read-only mode (env flag) for prod work.
Edge Function code runs in your project; avoid deploying code from chat without reviewing the diff.

Troubleshooting

Common errors and fixes

Unauthorized — invalid token

Token expired or wrong scope. Generate a new one at supabase.com/dashboard/account/tokens.

Verify: curl -H 'Authorization: Bearer $TOKEN' https://api.supabase.com/v1/projects

Branching tools fail with 'plan does not support branching'

Branching is Pro+. Upgrade plan or skip branching workflows.

Edge Function deploy fails: 'invalid Deno code'

Function code must be Deno-compatible (no Node-style require). Check imports use https://deno.land/... or npm: specifiers.

execute_sql returns 'permission denied'

The MCP uses a project-scoped role. For privileged ops, run via the dashboard SQL editor. Don't grant the MCP role superuser.

Alternatives

Supabase vs others

Alternative	When to use it instead	Tradeoff
Postgres MCP	You only need read-only SQL access and don't need Supabase-specific features	No branching, edge functions, auth introspection, or logs
Neon MCP	You're on Neon instead — also has branching	Different platform; no auth/edge functions
Supabase CLI directly	You want full local-dev flow with `supabase start`	No agent ergonomics; better for committed workflows

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills