The Supabase MCP server lets an AI client explore your database schema, run SQL, manage migrations and inspect projects. The official server is configurable and supports a read-only mode you should almost always use. Here is the safe setup for Claude Desktop and Cursor.
Step 1 — create a personal access token
In the Supabase dashboard, open Account → Access Tokens and create a new personal access token (PAT). Copy it. You will also want your project ref — find it under Project Settings → General → Project ID.
Step 2 — configure the client
Use read-only mode and scope to a single project by default:
{
"mcpServers": {
"supabase": {
"command": "npx",
"args": [
"-y",
"@supabase/mcp-server-supabase@latest",
"--read-only",
"--project-ref=your_project_ref"
],
"env": {
"SUPABASE_ACCESS_TOKEN": "sbp_your_token"
}
}
}
}
Restart the client; see MCP config file location if needed.
Why read-only and project scoping matter
--read-only restricts the database tools (execute_sql, apply_migration) to non-destructive queries — the AI cannot drop or mutate data. --project-ref scopes the server to one project, so account-level tools like list_projects disappear and the blast radius shrinks. Turn these off only when you explicitly need write access, and never against production. See MCP security best practices.
Verify
Ask: "List the tables in my Supabase project and show the columns of the users table." Real schema back means you are connected.
Common problems
Unauthorized/invalid token— wrong or rotated PAT, or it was created in a different account.- Write attempts fail — that is
--read-onlydoing its job; remove the flag only if you truly need writes. - Account tools missing — expected once you set
--project-ref; remove it to regain them. - No tools in client — Node 18+ required. See Claude Desktop MCP not loading.
Going further
Supabase fits a full-stack build stack with GitHub and filesystem servers. Browse curated loadouts or the databases category. Looking for the best database server overall? See best MCP server for Postgres.