Skip to content
MCP Shelf

Pod to App: Claude Code

How to install the Supabase MCP server in Claude Code

By Sophie Filer · Updated 10 Nov 2026 · Steps checked against Supabase's own docs on 10 Nov 2026

The short answer

Run the claude mcp add command below with your project ref, then open Claude Code, type /mcp, pick supabase and sign in. The URL keeps it to one project and read-only, which is how Supabase suggests you start.

Terminal
claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"
Sign-in
Supabase account, in the browser
Runs on
Supabase's hosted server
Safest mode
One project, read-only
Price
Free, Apache 2.0

Before you start

  • A Supabase project, ideally a development one or a branch, not production.
  • Its project ref: the short ID in your dashboard URL (supabase.com/dashboard/project/<ref>) or under Project Settings.
  • Claude Code, run from the project folder where you want the setting saved.

Install it step by step

  1. Step 1: Copy the command at the top of this page and replace YOUR_PROJECT_REF with your ref. Keep the quotes, since the URL has an & in it.
  2. Step 2: Run it in your normal terminal. --scope project writes the server to .mcp.json, so teammates get the same setup; there is no secret in it.
  3. Step 3: Start Claude Code with claude and type /mcp. Choose supabase, then Authenticate.
  4. Step 4: In the browser, sign in to Supabase and pick the organisation that owns the project.
  5. Step 5: Back in Claude Code, ask: "List the tables in my database and how many rows each has." It should answer from your real schema.

Choose what Claude Code can touch

Everything is controlled by the query string on the URL. Change it and add the server again to switch.

ParameterWhat it does
project_ref=...Limits the server to one project. Without it Claude Code can see every project in your account
read_only=trueRuns SQL as a read-only Postgres user and hides tools that change things
features=database,docsOnly these tool groups. Others include account, debugging, development, functions, branching and storage

Use it safely

Supabase is blunt about the risk: an agent with database access can be tricked by text stored in your own tables. Their advice, in short:

  • Point it at development data, not production.
  • Keep read-only on unless you need Claude Code to write, and then use a branch you can throw away.
  • Scope it to one project.
  • Leave manual tool approval on in Claude Code, so you read each SQL query before it runs.
  • Never hand this setup to your own customers; it acts with your developer permissions.

In CI, or against a local Supabase

Where nobody can click a browser sign-in, create a personal access token in your Supabase account settings and send it as a header:

Terminal
claude mcp add --transport http supabase "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true" -H "Authorization: Bearer YOUR_SUPABASE_TOKEN"

If you run Supabase locally with the CLI, it serves its own MCP server at http://localhost:54321/mcp. It has fewer tools and needs no sign-in.

If it does not work

What you seeWhat to do
supabase shows "needs authentication"Run /mcp in Claude Code and finish the browser sign-in.
It can see projects but not yoursYou picked the wrong organisation during sign-in. Clear the authentication in /mcp and choose the right one.
"Project not found"The ref in the URL is wrong or belongs to a different organisation.
Writes fail with a permission errorThat is read_only=true doing its job. Remove it only on a branch or development project.
Zsh says "no matches found"The URL is not in quotes, so the shell read the ?. Put it in double quotes.

MCP Shelf take

Is Supabase worth adding to Claude Code?

For Supabase work, this server changes what Claude Code can do: it reads your actual schema, writes migrations that fit it, checks the advisors for missing indexes and RLS gaps, and pulls logs when something fails. That is a big step up from pasting table definitions into a chat. The catch is that it is real database access. Keep it to one project, read-only, and a development database, and it is one of the most useful servers on the shelf. Give it write access to production and you are trusting every row of text in your tables.

Sophie Filer

Questions

Do I need a Supabase access token for Claude Code?

Not normally. Claude Code signs in through your browser when you run /mcp. A personal access token is only needed where no one can sign in, such as CI.

Can Claude Code change my Supabase database?

Only if you let it. With read_only=true in the URL, queries run as a read-only Postgres user and the tools that change things are hidden. Remove it to allow writes, ideally on a branch.

Where does Claude Code save the Supabase server?

With --scope project it goes into .mcp.json in the project folder, which is safe to commit because it holds no token. Leave the flag off to keep it only for you in that folder.

Sources: the steps on this page are written in our own words from Supabase's own install docs, the README, the README. If they disagree with this page, the project's docs win; please tell us from the server page.