Supabase MCP Server
Supabase's official hosted MCP server: control tables, SQL, migrations, and Edge Functions using natural language from Cursor, Claude Code, and more.
- Skill Road
- Supabase MCP Server
Categories
Description
The Supabase MCP Server is the official Model Context Protocol connection to your own Supabase projects, hosted by Supabase itself. Instead of switching between a database dashboard, terminal, and AI assistant, a coding agent connects directly to your Supabase project and can list tables, run SQL queries, apply migrations, manage Edge Functions, and search project documentation — all through natural language chat in Cursor, Claude Code, Windsurf, or other MCP-capable clients.
What the server does
Per the provider, the tool catalog is organized into feature groups that can be individually enabled or disabled: database (list tables, show Postgres extensions, apply migrations, execute SQL), debugging (log queries, security and performance advisors), development (project URL, API keys, generate TypeScript types from the schema), Edge Functions (list, retrieve, deploy), account management (manage projects and organizations, view costs), docs (search Supabase documentation), and experimental branching for paid plans. Storage tools are disabled by default and must be enabled separately if needed. All groups except Storage are therefore active from the start, but can be selectively disabled through the configuration UI in the Supabase dashboard.
Narrowing access
URL parameters let you scope the server precisely: read_only=true forces a read-only database user for all queries, project_ref=<id> binds the connection to a single project and automatically disables account management tools, and features=<groups> enables only selected tool groups. These parameters can be combined, for example ?project_ref=abc123&read_only=true, to strictly limit an agent to read-only access for a specific project — per Supabase, the recommended starting configuration for new connections.
Authentication
The hosted server at https://mcp.supabase.com/mcp uses dynamic client registration by default: the MCP client opens a browser window where you sign in with your Supabase account and grant the organization access — no personal access token is required. For local development with the Supabase CLI, the server is available at http://localhost:54321/mcp, though with a limited tool set and no OAuth 2.1. Self-hosted Supabase has the same limitation; there, MCP access must first be enabled via Supabase's own self-hosting documentation.
License and cost
The repository is licensed under Apache-2.0. The hosted MCP access itself does not add separate costs; it requires an existing Supabase account. The experimental branching tool additionally requires a paid Supabase plan.
Security risks
Supabase explicitly warns about the risks of connecting an AI agent with write access to a database: an agent with full access can apply migrations and execute arbitrary SQL, which can also modify or delete data. The provider therefore recommends setting up new connections with read_only=true first, scoping access to a single project via project_ref, and reading its own security best practices before first use.
Who benefits most
The server is especially useful for development teams already using Supabase as a backend: triggering schema changes directly from the editor, auto-generating TypeScript types from the database structure, and checking logs and performance advisors without switching to the dashboard. For read-only tasks — exploring the database structure, searching documentation — the read-only configuration alone is enough and minimizes any risk.
Requirements
An existing Supabase account with at least one project, plus an MCP client that supports remote servers over Streamable HTTP (e.g. Claude Code, Cursor, Windsurf). For local development, the Supabase CLI is sufficient.
Installation instructions
The Supabase MCP Server is hosted: nothing is installed locally, and the MCP client connects directly to https://mcp.supabase.com/mcp.
Step 1: Setting it up in Claude Code
claude mcp add --transport http supabase "https://mcp.supabase.com/mcp"
Then run claude /mcp, select "supabase", and confirm "Authenticate". A browser window opens for signing in with your Supabase account.
claude /mcp
Step 2: Scoping access tightly from the start
Rather than full access, most use cases are better served by an immediately scoped configuration:
claude mcp add --transport http supabase "https://mcp.supabase.com/mcp?project_ref=<project-id>&read_only=true"
project_ref binds access to exactly one project and automatically disables account management tools (no creating new projects, no managing organizations). read_only=true forces a read-only database user, so the agent can't apply migrations or modify data. Both parameters can be removed later once the agent proves reliable and write access is genuinely needed.
Setting it up in other clients
The official documentation provides an interactive URL builder: choose the platform, project, desired feature groups, and options, and the page automatically generates the right configuration for Cursor, Windsurf, and other clients.
Local development
Anyone running Supabase locally via the Supabase CLI can reach the MCP server at http://localhost:54321/mcp. This environment offers only a limited tool set, and OAuth 2.1 is not supported — sign-in works differently than with the hosted service.
Choosing feature groups deliberately
The features parameter can further narrow the tool set, for example features=database,docs to enable only database and documentation tools. Storage tools are disabled by default anyway and must be explicitly added via features=storage if needed.
Common connection issues
If OAuth sign-in fails with a project-related error, check whether the project ID given in the project_ref parameter actually exists and that the signed-in account has access to it. In local development via the Supabase CLI, a missing or misconfigured local instance prevents the client from connecting to http://localhost:54321/mcp — checking the CLI logs usually reveals the cause.
Step 3: Verifying the setup
After connecting, test with a harmless, read-only task, such as "Show me the tables in my project" or "Search Supabase documentation for Row Level Security." Only disable read-only mode once this works reliably and access is scoped to the correct project.
Following this order avoids the most common cause of accidental data changes with a new Supabase MCP connection: write access enabled too early against a production project.
A minute spent testing on the read-only endpoint is far cheaper than restoring a table after an unintended write.
Source: github.com/supabase-community/supabase-mcp and supabase.com/docs/guides/ai-tools/mcp, checked on 2026-09-06.
claude mcp add --transport http supabase "https://mcp.supabase.com/mcp"
Authentication
Dynamic client registration via browser login (default, no personal access token needed). The MCP client opens a browser window; after signing in, access is granted to the chosen organization. CLI and self-hosted environments don't support OAuth 2.1 and offer a limited tool set.
Required access permissions
Access can be granularly scoped via feature groups (database, debugging, development, Edge Functions, account management, docs, branching) as well as read_only=true and project_ref=<id>. Storage tools are disabled by default.
Transmitted or stored data
Requests run through Supabase-hosted infrastructure at mcp.supabase.com. Responses contain data from your own Supabase project (table structures, query results, logs, Edge Function configuration) and are returned to the MCP client and its language model.
Security risks
Without read_only=true, an agent can apply migrations and execute arbitrary SQL, which can also modify or delete data. Supabase recommends setting up new connections as read-only and scoped to a single project first, and only granting write access once a clear need is demonstrated.
License and costs
- License
- Apache-2.0
- Cost
- free
The MCP server itself is provided without a separate license or usage fee. It requires an existing Supabase account (free or paid, depending on project size); the experimental branching tool additionally requires a paid plan. Purchasing a Supabase plan happens exclusively on supabase.com, not through Skill Road.
Alternatives
Not recorded yet.
At a glance
- Provider
- Supabase
- Status
- Official server
- Deployment
- Remote
- Current version
- Not recorded yet.
- GitHub stars
- 3,014
- Last reviewed
- 06.09.2026
Repository and documentation
Categories
Supported clients
Related guides
Guides and background related to this entry.