StackMCP
Blog
·10 min read

How to Set Up and Use the Supabase MCP Server — Complete Guide

Step-by-step guide to the Supabase MCP server. Query databases, manage migrations, create Edge Functions, and monitor your project from your AI editor.

mcpsupabasedatabasesetupguidehow-to

The Supabase MCP server collapses your database dashboard, SQL editor, migration tool, Edge Function deployer, and log explorer into your AI editor. It is one of the most powerful MCP servers available -- 25 tools covering the entire Supabase platform -- and the single highest-impact addition for any project built on Supabase.

TL;DR: One access token gives the server full control over your Supabase account: tables, migrations, Edge Functions, branches, logs, and security advisors. Install with npx -y @supabase/mcp-server-supabase and authenticate with a personal access token from your Supabase dashboard.

Supabase MCP | npm | Tools: 25 | ~12,875 tokens

graph LR
    A[Your Editor] --> B[AI Assistant]
    B --> C[Supabase MCP Server]
    C --> D[Supabase API]
    D --> E[Database / Edge Functions / Logs]

What the Server Exposes

  • Project management: list_projects, get_project, get_project_url, get_publishable_keys, pause_project, restore_project
  • Database: list_tables, execute_sql, list_extensions -- arbitrary SQL including joins, CTEs, window functions, full-text search
  • Migrations: apply_migration, list_migrations -- tracked DDL with proper migration history
  • Edge Functions: list_edge_functions, get_edge_function, deploy_edge_function
  • Branches: create_branch, list_branches, delete_branch, merge_branch, reset_branch, rebase_branch
  • Monitoring: get_logs (7 services), get_advisors (security + performance)
  • Types: generate_typescript_types from your live schema
  • Org + cost: list_organizations, get_organization, get_cost, confirm_cost

Prerequisites

Generate a personal access token at supabase.com/dashboard/account/tokens. This single token gives full read-write access to all projects in your account. Treat it like a production credential.

You do not need your project ID upfront -- the server can discover it via list_projects.

Setup by Client

Claude Code

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

Or CLI: claude mcp add supabase -- npx -y @supabase/mcp-server-supabase

See the full Claude Code setup guide.

Cursor

Create .cursor/mcp.json:

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

See the Cursor setup guide.

VS Code (GitHub Copilot)

{
  "mcp": {
    "servers": {
      "supabase": {
        "command": "npx",
        "args": ["-y", "@supabase/mcp-server-supabase"],
        "env": {
          "SUPABASE_ACCESS_TOKEN": "sbp_your_token_here"
        }
      }
    }
  }
}

Real-World Workflows

Create a table with RLS policies

"Create a 'tasks' table with id, title, status, user_id (references auth.users), created_at. Enable RLS so users only see their own tasks."

  • Calls apply_migration with CREATE TABLE, ENABLE RLS, and CREATE POLICY statements
  • Migration is tracked in history
  • Verify immediately: "Run the security advisor" calls get_advisors

Write and apply a migration

"Add a 'priority' integer column to tasks and create an index on (user_id, status)."

  • Inspects current schema with list_tables before writing DDL
  • Calls apply_migration with a descriptive name
  • Migration appears in list_migrations output

Debug a production issue

"Query tasks for user_id '550e8400...' and check if RLS policies might be filtering results."

  • Runs execute_sql for the data query
  • Runs a second query against pg_policies for RLS inspection
  • Presents a coherent diagnosis in one turn

Deploy an Edge Function

"Create an Edge Function called 'stripe-webhook' that handles checkout.session.completed events."

  • Writes Deno-based function code
  • Calls deploy_edge_function with name, entrypoint, and files
  • Remember: set verify_jwt: false for public webhooks, or incoming requests get rejected with 401

Branch-based development

"Create a development branch called 'refactor-auth-schema'."

  • Calls get_cost + confirm_cost + create_branch
  • Branch gets its own project ID for isolated testing
  • "Merge the branch to production" calls merge_branch

Investigate logs

"Pull API and auth logs. Look for 500 errors or failed authentication attempts."

  • Calls get_logs for each service
  • Cross-references timestamps to build a timeline
  • Supports 7 services: api, postgres, auth, storage, edge-function, realtime, branch-action

Generate TypeScript types

"Generate the latest TypeScript types for my project."

  • Calls generate_typescript_types based on live schema
  • Apply a migration, regenerate types, update client code -- all in one conversation

Token Budget Impact

At ~12,875 tokens (~6.4% of 200K), Supabase MCP is one of the heavier servers. Practical combinations:

  • Supabase alone: comfortable
  • Supabase + GitHub MCP: ~23K tokens (~11.5%), very manageable
  • Supabase + GitHub + Stripe MCP + Sentry: ~43K tokens (~21.5%), workable for a fullstack stack

If you only occasionally touch Supabase, add it when needed and remove it when focused on frontend. See how to cut MCP token costs for more strategies.

Common Gotchas

DDL vs DML: which tool to use

  • apply_migration for schema changes (CREATE TABLE, ALTER, CREATE POLICY) -- tracked in history
  • execute_sql for data operations (SELECT, INSERT, UPDATE, DELETE) -- not tracked
  • Using execute_sql for schema changes works but causes migration drift

RLS pitfalls

Enabling RLS without policies blocks all access (except service-role). The security advisor catches this: get_advisors with type "security".

Branch project IDs

Development branches get their own project_ref. Reference branches by name and let the assistant resolve the ID.

Token scope

The access token grants full access to all projects in your account. No per-project scoping. Use separate accounts for truly isolated environments.

Edge Function JWT verification

Deployed functions require JWT by default. For webhooks from Stripe, GitHub, or third parties, explicitly disable: "Deploy with JWT verification disabled."

Paused projects

Free-tier projects pause after inactivity. Use restore_project through the MCP server to wake them up. Check status with get_project.

For more debugging help, see the MCP troubleshooting guide.

Pairing with Other Servers

  • GitHub MCP: Full dev loop -- DB branch, migration, types, push to GitHub, open PR
  • Stripe MCP: Classic SaaS pairing. Check webhook events, update subscription status in the database, deploy Edge Functions
  • Playwright MCP: Apply schema changes then verify the frontend still works
  • Context7 MCP: Ensures the assistant uses latest Supabase SDK patterns

For a comparison with the Firebase alternative, see Supabase MCP vs Firebase MCP.

Getting Started

Generate an access token, add the config block, reload your editor, and test with "List all projects in my Supabase account." Start with read-only operations, then move to migrations and Edge Functions once you trust the workflow.

For a pre-configured stack, see Next.js + Supabase or Indie Hacker.

Related Stacks

Next.js + Supabase StackFull-Stack Web Dev StackIndie Hacker Stack

Related Servers

Supabase MCP