How to Add Supabase MCP to Claude Code: Setup Guide

The Short Answer

To add Supabase MCP to Claude Code, run claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp", start claude in a regular terminal, type /mcp, select supabase, choose Authenticate and log in to Supabase in the browser. Pick the organization that holds your project, and Claude can list tables, run SQL, apply migrations and read logs.

That is Supabase's official hosted server from supabase-community/supabase-mcp, listed on mcp.so as Supabase MCP. Before you rely on it, spend two minutes on the safety options below: scoping it to one project and turning on read-only mode are both just URL parameters.

What You Need

• Claude Code, installed and signed in.
• A Supabase account with at least one project. A development project is the right place to start.
• A browser for the OAuth login. No API key is needed for interactive use.

There is nothing to install locally. The server is a remote Streamable HTTP endpoint, so Claude Code connects directly to https://mcp.supabase.com/mcp.

Step 1: Add the Server

The command from the Supabase MCP docs:

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp"

Supabase uses --scope project, which writes the server to .mcp.json in your repo root:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

That file holds no secrets, because each developer signs in with their own Supabase account, so it is safe to commit. Other scopes work too:

For how scopes, precedence and approvals work in general, see the Claude Code MCP guide.

Step 2: Log In With OAuth

1. Start claude in a regular terminal. Supabase's docs specifically say to authenticate from a terminal, not the IDE extension.
2. Type /mcp.
3. Select supabase, then Authenticate.
4. Log in to Supabase in the browser and choose the organization that contains the project you want Claude to work on.
5. Back in Claude Code, /mcp shows supabase as connected.

Claude Code stores and refreshes the token. If you are curious how the flow works under the hood, read MCP authentication and OAuth.

Step 3: Scope It to One Project and Make It Read-Only

The plain URL gives Claude access to every project in the organization you chose, with write access. Supabase's own security guidance recommends narrowing that. All of it is done with query parameters on the URL:

Your project ref is the ID in the dashboard URL, supabase.com/dashboard/project/your-project-ref. A scoped, read-only setup looks like this. Keep the quotes, because & means something to your shell:

claude mcp add --scope project --transport http supabase \
  "https://mcp.supabase.com/mcp?project_ref=your-project-ref&read_only=true"

If you already added the server, run claude mcp remove supabase first (add --scope project if that is where it lives), or edit the url in .mcp.json directly. You will be asked to authenticate again.

Feature groups

Every group except Storage is enabled by default. These are the values the features parameter accepts:

A sensible starting point for app development is features=database,docs,debugging,development. You lose the ability to deploy functions or create projects from chat, and Claude has fewer tool definitions to choose from. Note that account tools are skipped whenever you set project_ref.

The Supabase MCP page has an interactive URL builder if you would rather click than type.

Step 4: Verify

claude mcp list

Then in a session, /mcp should show supabase connected with its tool list. Ask something harmless first:

Use the supabase MCP to list the tables in my project and their row-level security status.

If you scoped it with project_ref, Claude should not need to ask which project you mean.

Example Prompts

• "List my tables and tell me which ones have RLS disabled."
• "Write a migration that adds a profiles table linked to auth.users, with RLS policies so users can only read and update their own row. Show it to me before applying it."
• "Generate TypeScript types for my database and save them to src/types/supabase.ts."
• "Check the security and performance advisors and fix the top issue."
• "Look at the last hour of API logs and explain the 500 errors."
• "Search the Supabase docs for how to set up realtime on a table, then implement it here."

The type-generation prompt is a good example of why this belongs in Claude Code rather than a chat app: Claude reads the live schema through MCP and writes the result straight into your repo.

Using a Token Instead (CI and Headless Runs)

OAuth needs a browser, so non-interactive runs such as claude -p in CI cannot complete it. Supabase's docs describe using a personal access token instead:

1. Create a token at supabase.com/dashboard/account/tokens. Scope it to the project the server connects to and grant only what your enabled tools need.
2. Set SUPABASE_ACCESS_TOKEN and SUPABASE_PROJECT_REF in the CI environment.
3. Commit a config that references them. Claude Code expands environment variables in .mcp.json URLs and headers:

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=${SUPABASE_PROJECT_REF}&read_only=true",
      "headers": {
        "Authorization": "Bearer ${SUPABASE_ACCESS_TOKEN}"
      }
    }
  }
}

Never put a real token in the file. Supabase recommends read-only mode for unattended monitoring and diagnostics routines like this.

Local and Self-Hosted Supabase

If you run Supabase locally with the Supabase CLI, the MCP server is at http://localhost:54321/mcp:

claude mcp add --transport http supabase-local http://localhost:54321/mcp

Per the README, the local and self-hosted servers offer a limited subset of tools and no OAuth 2.1. For self-hosted instances, follow Supabase's "Enabling MCP server" guide.

Security Checklist

Supabase's docs are unusually direct about the risks. The short version:

• Do not connect production unless the task needs production data. Use a development project or a branch.
• Use read-only mode whenever Claude only needs to look.
• Scope to one project with project_ref.
• Keep manual tool approval on in Claude Code, especially for execute_sql and apply_migration.
• Watch for prompt injection. Rows in your database can contain text written by users. If Claude reads a row that says "ignore previous instructions", that text reaches the model. Review what it proposes before you approve.
• Do not give the server to end users. It is a developer tool that acts with your permissions.

More on this in our MCP security best practices.

Troubleshooting

To see the raw tool list and responses, connect the server to the MCP Inspector.

Next Steps

Supabase MCP covers the database side. Add the GitHub MCP server so Claude can open a PR with the migration it wrote, and Playwright MCP to check the feature in a browser. For more databases and backend tools, browse the MCP server directory.