Supabase MCP in Claude Code: Read-Only Setup in 10 Minutes

The supabase mcp claude code integration connects your Supabase project to Claude Code through the Model Context Protocol, so Claude can inspect your schema, run SQL, draft migrations, and read logs as first-class tools. You register the server with claude mcp add, authenticate with a personal access token, and keep it read-only for safety.

Server URL, CLI flags, and read-only behaviour verified 31 July 2026 against Anthropic's Claude Code MCP documentation

If you have ever pasted table definitions into a chat so an AI could "understand" your database, the Supabase MCP server removes that step. Instead of copying context around, Claude Code talks to Supabase directly through a small, standardized bridge. This guide walks the full setup end to end, confirms the exact commands against the official docs, and spends real time on security, because you are about to give an AI agent a line into your database. Claude Code currently runs on the newest models like Claude Opus 5 and Sonnet 5, and we retest this setup regularly so the commands below stay accurate; the whole thing takes about 10 minutes. We ran through these steps ourselves before publishing, so the walkthrough reflects what actually happens on screen rather than a paraphrase of the docs.

What the Supabase MCP server is

It is the official MCP implementation for Supabase, turning your project database, edge functions, logs, and account operations into callable tools. Two variants exist: a hosted remote server at https://mcp.supabase.com/mcp and a local process launched with npx.

The Model Context Protocol (MCP) is an open standard for connecting AI tools to external systems. An MCP server exposes a system's capabilities as tools that a client like Claude Code can call. The Supabase MCP server is the official implementation for Supabase: it turns your project's database, edge functions, logs, and account operations into tools Claude can use.

Once connected, a supabase mcp claude code session lets Claude list your tables, run SELECT queries, apply migrations, generate TypeScript types, fetch project logs, and more, all without leaving the terminal. If you want the underlying mechanics of how Claude Code loads any server, the general add MCP to Claude Code walkthrough covers transports and scopes, and the broader Claude Code MCP overview explains how tools surface in a session. This article focuses on the Supabase-specific pieces.

There are two ways to run it. The hosted remote server lives at https://mcp.supabase.com/mcp and authenticates through your browser. The local server runs on your machine via npx and authenticates with a token. Both give you the same tools; the difference is where the process runs and how you sign in. We will set up both.

Prerequisites for the supabase mcp claude code setup

You need a Supabase account and project, a personal access token, your project ref from the Project ID setting, Node and npx if you plan to run the server locally, and an installed, authenticated Claude Code.

Before you begin the supabase mcp claude code setup, make sure you have the following in place. It is a short list, but every item matters.

• A Supabase account and project. If you are experimenting, create a fresh development project rather than pointing Claude at production data.
• A Supabase personal access token (PAT). You create this in your Supabase account settings. Treat it like a password.
• Your project ref. This is the project's unique ID, found under Project ID in your project's settings. It also appears as the subdomain in your project URL.
• Node.js and npx if you plan to run the local server. The server is distributed as an npm package, so you need a working Node install. Our guide to Node.js for Claude Code covers getting that right.
• Claude Code installed and authenticated. If you are new to the tool itself, start with what is Claude Code.

Step 1: Create a Supabase personal access token

Open your Supabase account settings, go to Access Tokens, generate one named something like claude-code-dev, and copy it immediately — the value is shown only once. It authenticates as you, across every project your account can reach.

Log in to Supabase, open your account settings, and find the Access Tokens page. Generate a new token, give it a descriptive name like claude-code-dev, and copy it immediately, because Supabase only shows the value once.

This token authenticates the server as you, with your permissions across the projects your account can reach. That is exactly why scoping and read-only mode (covered below) matter so much. Never paste the token into a file that gets committed, a shared chat, or a screenshot. Store it in a secrets manager or an environment variable, and rotate it if it ever leaks.

Step 2: Add the Supabase MCP server to Claude Code

Two options. The hosted server registers with claude mcp add --transport http and a URL carrying project_ref and read_only=true. The local server runs @supabase/mcp-server-supabase over stdio with your token in the environment.

Now register the server. Pick one of the two approaches below.

Option A: The hosted remote server (simplest)

The remote server uses HTTP transport and signs you in through the browser, so there is no token to manage locally. Add it, scoped to a single project and read-only, like this:

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

The remote server takes its configuration as URL query parameters: project_ref scopes it to one project, read_only=true runs database queries as a read-only Postgres user, and features=<groups> can limit which tool groups load. After adding it, run /mcp inside a Claude Code session to trigger the OAuth login flow and authorize access.

Option B: The local server via npx

The local server runs the @supabase/mcp-server-supabase package on your machine and reads your token from an environment variable. This is the path many people mean when they talk about a supabase mcp claude code install from the command line:

claude mcp add --env SUPABASE_ACCESS_TOKEN=<your-token> --scope local supabase \
  -- npx -y @supabase/mcp-server-supabase@latest --read-only --project-ref=<your-ref>

A few things are happening here, and the order is deliberate:

• Everything before the -- is a flag for Claude Code itself. --env passes your token into the server's environment, and --scope local sets where the config is stored.
• Everything after the -- is the command Claude Code runs to start the server: npx -y @supabase/mcp-server-supabase@latest with the server's own --read-only and --project-ref flags.
• The --read-only flag restricts the database tools (execute_sql and apply_migration) to read-only queries. Note that it governs the SQL tools specifically, not account-level tools, which is another reason to also scope with --project-ref.

You can also omit --env and export SUPABASE_ACCESS_TOKEN in your shell before running the command; the server reads it either way, and keeping it out of shell history is safer.

Step 3: Pick a scope

Three scopes exist: local for you alone in the current project, project for a checked-in .mcp.json shared with your team, and user for every project on your machine. Never put a token in a project-scoped config.

MCP servers in Claude Code are stored at one of three scopes, and choosing well saves headaches later:

• local (the default): available only to you, only in the current project.
• project: shared with everyone via a checked-in .mcp.json file. Do not put tokens in a project-scoped config.
• user: available to you across every project on your machine.

For a personal database, local or user is usually right. If your team shares the config, prefer the remote server (which uses browser OAuth, so no secret lands in the file) at project scope. The general add-MCP guide linked above goes deeper on when each scope fits.

Step 4: Verify the connection

Run claude mcp list and look for supabase with a connected status, then open a session and run /mcp to view the tools and finish any pending OAuth. Asking Claude to list your tables is the live confirmation.

Confirm the server registered and is healthy:

claude mcp list

A working supabase mcp claude code connection shows supabase with a ✓ Connected (or similar healthy) status. Then start Claude Code and run /mcp in the session to see the server's tools and complete any pending OAuth. Our dedicated claude mcp list reference explains how to read that output and what a failed status means. If everything is green, ask Claude something simple like "list the tables in my Supabase project" to confirm the tools actually respond.

Here is the whole flow at a glance.

Security best practices for the supabase mcp claude code integration

Keep --read-only on by default, scope to one project with the project ref, prefer a development project over production, never commit the token, expect prompt injection from row and log content, and never expose the server to end users.

This is the most important section, so treat it as required reading, not an afterthought. A supabase mcp claude code integration gives an AI agent a path to your data, and the official Supabase guidance is explicit about the risks.

• Use --read-only unless you genuinely need writes. Read-only mode runs SQL as a restricted Postgres user, so a bad query or a bad instruction cannot drop a table. Turn writes on only for a specific task, then turn them back off.
• Scope to one project with the project ref. Your token can reach every project your account can, so --project-ref (or project_ref) is what stops Claude from touching an unrelated project.
• Prefer a development project over production. Supabase recommends pointing the server at a dev project. Let Claude iterate against data you can afford to lose.
• Never commit your token. Keep it out of .mcp.json, shell scripts, and screenshots. The remote server sidesteps this entirely by using browser OAuth instead of a stored secret.
• Mind prompt injection. If Claude reads a table row or a log line that contains hostile instructions, those can influence its next action. Read-only mode and project scoping are your guardrails.
• Do not expose it to end users. The server acts with your developer permissions; it is a tool for you, not something to wire into a customer-facing product.

We connect Claude Code to real infrastructure every day building this site, and read-only is the one setting we never treat as optional on first contact. The reasoning is unglamorous but real: an agent that has been reasoning cleanly ninety-nine steps in can still misread a schema on step one hundred and reach for a write it should not. Starting a supabase mcp claude code session locked to read-only means the worst a wrong turn does is return the wrong rows, not delete the right ones — so we only flip writes on for the one migration we're actively watching, then flip them straight back off.

What you can do once it is connected

You describe intent instead of typing SQL: inspect a schema for missing indexes, run a SELECT for recent signups, draft a migration for review, generate TypeScript types, or summarize the last hour of edge function logs.

With the tools live, a supabase mcp claude code workflow feels less like typing SQL and more like describing intent. Some realistic prompts:

• "Inspect the orders schema and tell me which columns lack indexes." Claude uses list_tables and related tools to read the structure.
• "Write a query for the ten most recent signups and run it." With read-only on, execute_sql returns rows safely.
• "Draft a migration that adds a deleted_at column to users." Claude can prepare an apply_migration call for you to review before it runs.
• "Generate TypeScript types for my database." The generate_typescript_types tool produces types you can drop straight into an app.
• "Pull the last hour of edge function logs and summarize the errors." Debugging tools like get_logs and get_advisors feed Claude the context.

Because Claude can now read real schema, the code it writes fits your actual tables instead of a guess. Pair this with Claude Code subagents and you can hand a whole "check the database, then implement the change" task to a focused agent.

Troubleshooting

The server shows failed or disconnected in claude mcp list. The usual causes are a bad or expired token, a wrong --project-ref, or npx not finding the package. Regenerate the token, double-check the ref against your Project ID, and confirm Node is installed by running npx -y @supabase/mcp-server-supabase@latest --help on its own.

claude mcp add rejects your command or eats a flag. For local (stdio) servers, every Claude Code option must come before the server name, and the server's own flags must come after the --. If you put --read-only before the name, Claude Code tries to parse it as its own flag and fails. There is a related gotcha: if the server name comes directly after --env, the CLI reads the name as another KEY=value pair, so keep at least one other option (like --scope local) between --env and the name.

Claude will not run writes. That is --read-only working as intended. Remove the flag (or set read_only=false on the remote URL) only for the specific write task, then restore it.

Node or npx is missing. The local server needs Node. Install it, or switch to the hosted remote server, which requires no local runtime at all.

Wrapping up

Create a token, register the server scoped to a single project, keep read-only enabled, and verify with claude mcp list. That small amount of configuration replaces schema guessing with Claude reading your real tables.

A supabase mcp claude code setup is a small amount of configuration for a large jump in capability: Claude Code stops guessing at your schema and starts working from the real thing. Create a token, add the server scoped to one project, keep it read-only, verify with claude mcp list, and you are done. For the deeper mechanics, lean on the official Claude Code MCP documentation and the Supabase MCP guide, and start against a development project until you trust the workflow.