Ask Claude Code to write a query against your Supabase database and it guesses: column names from the variable names in your code, a user_id that’s actually owner_id, a migration that collides with one you already ran. It can’t see the schema, so you end up pasting table definitions into the chat.
Supabase MCP is Supabase’s official server. It lets Claude Code list your tables, run SQL, read logs, check security advisors, and generate TypeScript types straight from the real database. It’s hosted, signs in with OAuth, and this guide sets it up read-only and scoped to one project by default, which is how Supabase recommends starting.
Comparing options? Our database and backend MCP roundup covers the alternatives.
Quick Start
Run this in your project folder, with your project ref in place of the placeholder:
claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true"
Start Claude Code, run /mcp, pick supabase, and approve access in the browser. Total time: about 2 minutes. No token to create or paste.
⚡ Copy This Prompt: Let Claude Code Install and Verify It For You
Skip the manual steps below and hand the whole job to the agent instead:
You have shell access and the `claude mcp` CLI on this machine. Connect the Supabase MCP server to Claude Code for this project in read-only mode and report back. Do not tell me it's done unless step 4 actually confirms it:
1. Run `claude mcp list`. If a supabase entry already exists, show me its URL and stop instead of adding a second one.
2. Ask me for my project ref (Project Settings > General in the Supabase dashboard, or the part before .supabase.co in my project URL). Then run:
`claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true"`
with the placeholder replaced.
3. Tell me to run `/mcp` in Claude Code, pick supabase, and finish the Supabase sign-in in my browser, choosing the organization that owns this project. Wait until I say it's done, then run `claude mcp list` and confirm supabase shows Connected.
4. Call `list_tables` and summarize the tables in the public schema with their row counts. Don't run any other SQL yet.
Never ask me to paste an access token or database password into this chat. If any step fails, give me the exact error and the command that produced it. Do not skip ahead.
The last step only reads table names, so you can see what Claude sees before it runs a single query.
What You’ll Need
| Requirement | Why You Need It | Time |
|---|---|---|
| Claude Code installed | The client that calls the Supabase tools | 0 min |
| A Supabase account and project | The server signs in as you and only sees organizations you pick at login | 0 min |
| Your project ref | Scopes the server to one project. Find it in Project Settings > General | ~30 sec |
Step-by-Step Setup
Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.
Step 1 — Build the URL
~30 sec
The hosted server takes three options as query parameters on https://mcp.supabase.com/mcp:
| Parameter | What It Does |
|---|---|
project_ref=<id> |
Limits the server to one project and removes account-level tools like create_project
|
read_only=true |
Runs every query as a read-only Postgres user and hides tools that change things. Off by default |
features=<groups> |
Comma-separated list of tool groups to enable, e.g. database,docs
|
Supabase’s dashboard has a URL builder too: open your project, click Connect, then the MCP tab.
Step 2 — Add the server
~30 sec
--scope project writes the entry to .mcp.json in your repo, so it only applies to this project and teammates get the same config:
claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true"
Keep the quotes: without them your shell treats the & as “run in the background” and cuts the URL off.
Real run, October 2026, with a placeholder project ref (use yours from Step 1). The confirmation line drops the query string, but .mcp.json keeps read_only=true, so check the file, not the message. Pending approval is normal for a project-scoped server: start claude, approve it, then sign in with /mcp.
Step 3 — Sign in with OAuth
~1 min
Inside Claude Code, run /mcp, select supabase, and choose Authenticate. In the browser, pick the organization that owns the project, then approve. Claude Code stores the token, so you do this once.
Read-only and scoped to one project: Claude Code can look at your database but not change it.
What Each Piece Does
| Feature Group | Tools | Default |
|---|---|---|
database |
list_tables, list_extensions, list_migrations, apply_migration, execute_sql
|
On |
debugging |
get_logs, get_advisors (security and performance checks) |
On |
development |
get_project_url, get_publishable_keys, generate_typescript_types
|
On |
functions |
List, read, and deploy Edge Functions | On |
branching |
Create, merge, reset, and delete development branches | On |
docs |
search_docs across Supabase’s current documentation |
On |
account |
List orgs and projects, create, pause, or restore projects. Removed when you set project_ref
|
On |
storage |
List buckets, read and update storage config | Off |
With read_only=true, tools that change things (apply_migration, deploy_edge_function, branch changes) aren’t available at all.
Verify It’s Actually Working
claude mcp list
✔ supabase https://mcp.supabase.com/mcp?project\_ref=… (HTTP) – Connected
! supabase Needs authentication → run /mcp and sign in (Step 3)
✘ supabase Failed to connect → check the URL is quoted and the transport is http
Then ask for something only the live database knows:
List the tables in my public schema, then generate TypeScript types for them and tell me which tables have Row Level Security disabled.
If Claude calls list_tables, generate_typescript_types, and get_advisors and the answer matches your dashboard, it’s working.
Common Mistakes to Avoid
- Pointing it at production first. Supabase’s own advice is to connect to a development project, or a development branch, and use production only when a task really needs production data.
- Assuming read-only means RLS applies. Read-only mode queries as a role that can read all data, ignoring Row Level Security. It stops writes, not reads. Anything in the database is visible to the model.
-
Auto-approving every tool call. Table rows can contain text written by your users, and an LLM can be tricked by instructions hidden in that text. Supabase wraps SQL results in warnings, but keep manual approval on for
execute_sql. A Claude Code hook can enforce that. -
Picking the wrong organization at login. The server only sees the organization you approve. If
list_tablessays the project doesn’t exist, run/mcpagain and choose the right one. -
Leaving the URL unquoted. The
&between parameters splits the command in bash and zsh, soread_only=truesilently never makes it into the config.
Q&A
Is it free?
Yes. The MCP server costs nothing extra; you pay for your Supabase project as usual. Tools that create projects or branches can add cost, and Claude has to confirm the cost with you first.
How do I let it write, run migrations, or deploy functions?
Remove read_only=true from the URL (claude mcp remove supabase, then add it again). Do it on a development branch, not production.
Does it work with local Supabase?
Yes. With the Supabase CLI running, the server is at http://localhost:54321/mcp. It has fewer tools and no OAuth sign-in.
Can I use it in CI without a browser login?
Yes. Create a personal access token in the Supabase dashboard and pass it as an Authorization: Bearer header. Keep it in an environment variable, never in the repo.
How do I remove it?
claude mcp remove supabase --scope project.
Official Resources
- Supabase MCP docs — setup per client, options, security
- supabase/mcp on GitHub — source and changelog
- Supabase Branching — a safe copy of your database to point the agent at
-
Claude Code MCP docs —
claude mcp add, scopes, and OAuth with/mcp
Originally published at quickpromptco.com, where the guide is kept up to date.
Top comments (0)