Adding the Supabase MCP server to Claude Code lets Claude inspect your schema, query data, and reason about your database directly inside a coding session — no copy-pasting table definitions or SQL. This is the single most-searched MCP setup for Claude Code, and it's straightforward once you know the token and scope decisions. Here's the clean version, including the security setting most guides skip.
Exact package names and flags for the Supabase MCP server change as it evolves. The workflow and the security decisions below are stable; confirm the current command and token steps in the official Supabase MCP docs and the Claude Code MCP docs. This guide is about doing it correctly, not just quickly.
What the Supabase MCP server actually does
Once connected, Claude Code can (depending on the access you grant):
- Read your database schema — tables, columns, relationships
- Run queries against your data while debugging
- Inspect and help with migrations
- Reason about your Supabase project structure without you describing it
That last point is the value: instead of pasting your schema into the conversation every time, Claude reads it live. If you're new to MCP generally, start with how to use MCP servers with Claude Code — this post is the Supabase-specific deep dive.
Prerequisites
- Claude Code installed and working (setup guide)
- A Supabase account and the project you want to connect
- A Supabase personal access token (created in your Supabase account settings)
Step 1 — Create a scoped access token
In your Supabase dashboard, generate a personal access token. Treat this like a password — it grants programmatic access to your project. Two rules that matter:
- Scope it to the project you're working on, not your whole account, where possible
- Store it in an environment variable, never hard-coded into a committed config file
Step 2 — Add the server to Claude Code
The Supabase MCP server is added like any other MCP server, via the claude mcp add command. The general shape:
claude mcp add supabase <command-to-run-the-supabase-mcp-server>
The exact package and arguments (project ref, token via env var, flags) are specified in the official Supabase MCP documentation — check there for the current invocation, since the package evolves. The important part you control is how you pass the token (environment variable) and what scope you choose next.
Step 3 — Choose the right scope
This is the decision people get wrong. When you add the server, Claude Code stores it at one of three scopes:
- Local — only you, only this project. Good for personal experiments.
- Project — committed to the repo (
.mcp.json), shared with everyone working on it. Good for a team that all needs the same database access. - User — available to you across every project.
For a database connection, project scope leaks risk: everyone who clones the repo inherits the server config. Keep the token in an environment variable each developer sets locally, even if the server entry is project-scoped. Never commit the token itself.
Step 4 — Use read-only mode (the setting most guides skip)
The Supabase MCP server can be run in a read-only mode. Use it unless you have a specific reason not to.
Claude is good, but it operates on your instructions and its own judgement. A read-only connection means the worst case is a bad SELECT, not a dropped table. Grant write access only when a task genuinely needs it, and prefer doing destructive operations yourself. This single setting is the difference between "Claude helped me debug a query" and a very bad afternoon.
Step 5 — Verify it works
Start Claude Code in your project and ask something that requires the database:
claude
> What tables are in my Supabase project and how are they related?
If Claude returns your actual schema, the connection, token, and scope are all working.
Removing or changing the server
- List configured servers:
claude mcp list - Remove it:
claude mcp remove supabase - Changed your token? Remove and re-add with the new value in the environment variable.
Troubleshooting
- Claude can't see the database — token missing or wrong scope. Confirm the env var is set in the shell where you launch Claude Code.
- Auth/permission errors — the token may be scoped too narrowly, or expired. Regenerate and re-add.
- Works for you, not teammates — classic project-scope mistake: the server entry is shared but each person needs their own token in their own environment variable.
- Server not found on add — you likely have the package name/command slightly wrong; check the current official Supabase MCP docs for the exact invocation.
FAQ
How do I add Supabase MCP to Claude Code?
Create a scoped Supabase personal access token, then run claude mcp add supabase <server command> with the token passed via an environment variable. Choose the scope deliberately and enable read-only mode unless you need writes. Verify by asking Claude about your schema.
Is it safe to connect Supabase to Claude Code?
Yes, if you use a scoped token, keep it in an environment variable (never committed), and run the server in read-only mode. The risk is proportional to the access you grant — least privilege keeps it safe.
Where does the Supabase MCP config go?
In Claude Code's MCP configuration at the scope you choose. Project scope writes to a shared .mcp.json in the repo — but the token itself must stay in a per-developer environment variable, not in that file.
Should I use project or local scope for Supabase MCP?
Local for personal experiments. Project scope only when the whole team needs the same access — and even then, never commit the token; each developer supplies their own via environment variable.
How do I remove the Supabase MCP server?
Run claude mcp remove supabase. Use claude mcp list first to confirm the exact server name you registered it under.
Can Claude Code modify my Supabase database?
Only if you grant write access. Run the server read-only by default — then the worst case is a bad query, not data loss. Grant writes only for tasks that require them, and do destructive operations yourself.
Next step
Connecting your database is the point where Claude Code stops guessing and starts reasoning about your real system. The same leverage applies to how you instruct it — encode your standards once with skills instead of re-explaining them every session.