
Supabase MCP Server
Manage Supabase projects, tables, migrations, logs and Edge Functions.
- Needs your setup first
- ★ 3K GitHub stars
- Last commit 28 Oct 2026
What is Supabase?
The Supabase MCP server is Supabase's official hosted MCP server, letting AI assistants manage Supabase projects: run SQL, apply migrations, create branches, deploy edge functions and search the docs.
- Tools
- 29
- Runs on
- Hosted
- Licence
- Apache-2.0
- GitHub stars
- 3K
Good for
- Building a Supabase app with Cursor or Claude Code
- Checking logs and advisories when something breaks
- Writing and applying migrations
You'll need
- A Supabase account
Needs your setup firstIt needs something our Linux test machine does not have (an account, a desktop app, a Mac or a running service), so on 26 Oct 2026 we listed its tools from its package instead of running this config. The npm package called "supabase-mcp" comes from a different repository (Cappahccino/SB-MCP). Supabase's own server is the hosted URL above; their local package is @supabase/mcp-server-supabase.
MCP Shelf take
Supabase needs something our Linux test machine does not have (an account, an app or a service), so on 26 Oct 2026 we ran its package and counted 29 tools. 18 of the 29 only read; the other 11 can change things. 28 of 29 come with a useful description, all of them say whether they change things, and the tool list costs about 2,200 tokens of context before you ask a thing. Other directories point at a package with the same name that belongs to someone else; the config on this page installs the real one. It sits 5th of 6 in its category on our shelf by GitHub stars (3K).
What can Supabase read and change?
It can read
- Projects, organisations, schemas, logs and advisor reports for the account you sign in with
- Supabase's public docs
It can change
- Database rows and schema through SQL and migrations
- Projects and branches, which can add to your bill
- Deployed Edge Functions
Safer setup: Use a development project, not production, and add project_ref plus read_only=true to the URL. Supabase also advises keeping manual approval of each tool call switched on in your client.
Supabase in more detail
Supabase maintains this server. It covers the whole project, not just the database: list and create projects, run SQL, apply migrations, read logs, generate TypeScript types and deploy Edge Functions.
The easiest setup is the hosted server, which signs you in with your Supabase account in the browser. You can scope it to one project and to read-only from the URL.
- Made by
- Supabase
- Last commit
- 28 Oct 2026
- Setup checked
- 27 Oct 2026
- Page updated
- 27 Oct 2026
What's in the pod
What tools does Supabase have?
We found 29 tools when we ran its package, before any sign-in or app was connected, on 26 Oct 2026. 18 only read. The rest can change things, so keep your app's "ask before each tool call" setting on for them.
How we tested it: Listed by the npm build of the same server (v0.14.0) with its default feature groups and a placeholder token; search_docs was added from the source, as it needs the docs API to load. The hosted URL on this page needs a Supabase sign-in.
Runs commands1 tool · Can start programs or run code.
| Tool | What it is for |
|---|---|
execute_sql | Runs a SQL query against the project's Postgres database and returns the rows. |
Changes things10 tools · Can create, edit, send or delete.
| Tool | What it is for |
|---|---|
apply_migration | Runs a schema change as a named migration so it is tracked like any other. |
create_branch | Spins up a development branch of a project to try changes safely. |
create_project | Starts a new Supabase project in the organisation and region you choose. |
delete_branch | Removes a development branch you no longer need. |
deploy_edge_function | Uploads and deploys an Edge Function from code the agent wrote. |
merge_branch | Merges a branch's migrations and functions back into production. |
pause_project | Pauses a project so it stops running. |
rebase_branch | Brings a branch up to date with migrations added to production since it was made. |
reset_branch | Rolls a branch's migrations back to an earlier version. |
restore_project | Wakes a paused project up again. |
Only reads18 tools · Looks things up and changes nothing.
| Tool | What it is for |
|---|---|
confirm_cost | Asks you to accept the price before a new project or branch is created. |
generate_typescript_types | Builds TypeScript types from the current database schema. |
get_advisors | Lists security and performance warnings, such as tables missing row level security. |
get_cost | Tells you what a new project or branch would cost before you make it. |
get_edge_function | Fetches the source of one deployed Edge Function. |
get_organization | Shows one organisation's details and plan. |
get_project | Shows one project's details, region and status. |
get_project_url | Returns the API URL your app uses to reach the project. |
get_publishable_keys | Returns the public keys a front end needs to talk to the project. |
list_branches | Lists a project's development branches and their state. |
list_edge_functions | Lists the Edge Functions deployed in a project. |
list_extensions | Shows which Postgres extensions are installed. |
list_migrations | Lists the migrations already applied to the database. |
list_organizations | Lists the organisations your account belongs to. |
list_projects | Lists every project you can reach. |
list_tables | Lists tables in the chosen schemas, with their columns. |
query_logs | Pulls recent logs for the API, Postgres, auth, storage or functions to help debug. |
search_docs | Searches Supabase's documentation for an up-to-date answer. |
Grouped and described by us. The README on GitHub lists the inputs each tool takes.
How clearly it describes its tools to your assistant
- Tools with a description
- 28 of 29
- Say if they change things
- 29 of 29
- Context it takes, at least
- ~2,200 tokens
Every tool says whether it only reads or can change things, so a client can ask before the risky ones.
From the tool list it sent us. The token figure counts names, descriptions and input names; the full schemas your client loads add more.
How do I install Supabase?
Install steps from the Supabase README
The project's own instructions, copied from its README on GitHub on 27 Oct 2026 under its Apache-2.0 licence. They are the source of truth; the ready-made configs further down are built from them. The rest of the README is in the README tab.
Setup
1. Follow our security best practices
Before setting up the MCP server, we recommend you read our security best practices to understand the risks of connecting an LLM to your Supabase projects and how to mitigate them.
2. Configure your MCP client
To configure the Supabase MCP server on your client, visit our setup documentation. You can also generate a custom MCP URL for your project by visiting the MCP connection tab in the Supabase dashboard.
Your MCP client will automatically prompt you to log in to Supabase during setup. Be sure to choose the organization that contains the project you wish to work with.
Most MCP clients require the following information:
{
"mcpServers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp"
}
}
}
If you don't see your MCP client listed in our documentation, check your client's MCP documentation and copy the above MCP information into their expected format (json, yaml, etc).
CLI
If you're running Supabase locally with Supabase CLI, you can access the MCP server at http://localhost:54321/mcp. Currently, the MCP Server in CLI environments offers a limited subset of tools and no OAuth 2.1.
Self-hosted
For self-hosted Supabase, check the Enabling MCP server page. Currently, the MCP Server in self-hosted environments offers a limited subset of tools and no OAuth 2.1.
Configuration options and tools
See the Supabase MCP Server docs for the full list of available tools and configuration options.
The docs also feature an interactive URL builder to populate configuration options for you.
Usage with AI SDK's MCP Client
The @supabase/mcp-server-supabase package exports createToolSchemas() to populate input and output schemas for Vercel AI SDK's MCP client. This allows Supabase MCP tools to be treated as static tools with client-side validation and inferred TypeScript types for their inputs and outputs.
import { createToolSchemas } from '@supabase/mcp-server-supabase';
import { createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';
const mcpClient = await createMCPClient({
transport: {
type: 'http',
url: 'https://mcp.supabase.com/mcp',
},
});
const tools = await mcpClient.tools({
schemas: createToolSchemas(),
});
const result = streamText({ model, tools, prompt: '...' });
for (const step of await result.steps) {
for (const toolResult of step.staticToolResults) {
if (toolResult.toolName === 'get_project_url') {
toolResult.input; // { project_id: string }
toolResult.output; // { url: string }
}
}
}
createToolSchemas() accepts similar filtering options as the MCP server's URL parameters:
features: Restrict to specific feature groups (e.g.['database', 'docs']). Defaults to all default feature groups.projectScoped: Whentrue, omitsproject_idfrom tool input schemas and excludes account-level tools — use when connecting to a server configured withproject_ref. Defaults tofalse.readOnly: Whentrue, excludes mutating tools — use when connecting to a server configured withread_only=true. Defaults tofalse.
const mcpClient = await createMCPClient({
transport: {
type: 'http',
url: 'https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs',
},
});
const tools = await mcpClient.tools({
schemas: createToolSchemas({
features: ['database', 'docs'],
projectScoped: true,
readOnly: true,
}),
});
Note: This server does not send
structuredContentin MCP tool results. AI SDK falls back to parsing JSON fromcontenttext.
For more information, see Schema Definition and Typed Tool Outputs in the AI SDK docs.
What you need first
- A Supabase account
Add Supabase to your app
Pick your app for a ready-to-paste snippet and where it goes, built from the steps above.
Where it goes: Your terminal, in the project folder
claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF&read_only=true"Then sign in from a normal terminal: run claude /mcp, pick supabase and choose Authenticate, and select the organisation that owns the project. Drop read_only=true only on a development project.
Where it goes: ~/.cursor/mcp.json, or .cursor/mcp.json in a project
{
"mcpServers": {
"supabase": {
"url": "https://mcp.supabase.com/mcp"
}
}
}Cursor signs you in to Supabase in the browser. Check the connection under Settings → Cursor Settings → Tools & MCP, and restart Cursor if tools are missing.
Where it goes: Settings → Connectors → Add custom connector
https://mcp.supabase.com/mcpPaste the URL and sign in if asked. Custom connectors depend on your plan.
Where it goes: .vscode/mcp.json in your project
{
"servers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp"
}
}
}Where it goes: ~/.codex/config.toml, shared by the Codex CLI, IDE extension and ChatGPT desktop app
[mcp_servers.supabase]
url = "https://mcp.supabase.com/mcp"Or run: codex mcp add supabase --url https://mcp.supabase.com/mcp, then codex mcp login supabase if it asks you to sign in.
Where it goes: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"supabase": {
"serverUrl": "https://mcp.supabase.com/mcp"
}
}
}Where it goes: chatgpt.com/plugins → + → Add custom MCP server
https://mcp.supabase.com/mcpPaste the URL as the server address, choose OAuth if it asks you to sign in, create it as a plugin, then install it before using it in a chat. Workspace admins can block custom servers.
Add ?project_ref=your-project-ref&read_only=true to the URL to lock it to one project and to read-only queries.
Checked against the project's own install docs on 27 Oct 2026: supabase-community/supabase-mcp README, supabase.com/docs/guides/getting-started/mcp.
Did this work for you?
Projects change their install steps often. If Supabase did not install, or something here no longer matches the project, tell us and we will check it against the README and fix the page.
New to this? See the setup guides for Claude Code, Cursor, Claude Desktop, VS Code, Codex and ChatGPT. If it will not start, test it in MCP Inspector and look up the error in Fixing MCP server errors.
Supabase not working? Common fixes
- The agent works on the wrong project
- Add ?project_ref=<your project ref> to the server URL so it can only see that one.
- Sign-in picks the wrong organisation
- Disconnect and reconnect, then choose the organisation that owns the project on the Supabase consent screen.
- Tools are missing on a local or self-hosted stack
- The CLI and self-hosted servers only offer a subset of tools. Account and branching tools need the hosted URL.
- An old client cannot connect
- The server only speaks the current MCP protocol. Update your client to a recent version.
How do I configure Supabase?
Names are exactly as the project spells them. Required ones are marked.
| Setting | What it does |
|---|---|
https://mcp.supabase.com/mcpConfig · required | The hosted server address. Your client opens a Supabase sign-in the first time you connect. |
project_refConfig | Add to the URL to lock the agent to one project. Account-wide tools such as creating projects disappear.?project_ref=abcdefghijklmnop |
read_onlyConfig | Add read_only=true to the URL and every tool that changes data is left out.&read_only=true |
featuresConfig | Comma-separated tool groups to switch on: account, database, debugging, development, docs, functions, branching, storage.&features=database,docs |
http://localhost:54321/mcpConfig | Address of the smaller tool set served by a local stack started with the Supabase CLI. |
Supabase FAQ
How do I add the Supabase MCP server to Claude Code?
Run claude mcp add --scope project --transport http supabase with the URL https://mcp.supabase.com/mcp plus ?project_ref=YOUR_PROJECT_REF&read_only=true, then authenticate from a normal terminal with claude /mcp. The dashboard's MCP connection tab builds the URL for you.
Do I need a Supabase access token for MCP?
Not for the hosted server. Your client signs in to Supabase with OAuth in the browser; just pick the organisation that contains the project you want. Local CLI and self-hosted stacks have no OAuth and offer fewer tools.
Is it safe to connect the Supabase MCP server to production?
Supabase itself advises against it. Data returned by a query could carry instructions that trick the model, so use a development project, add read_only=true to run as a read-only Postgres user, scope it with project_ref and keep approving each tool call.
Is the Supabase MCP server free?
The server is free and Apache 2.0 licensed. Some actions, such as creating projects or branches, can add charges to your Supabase bill, so it shows the cost and asks you to confirm before doing them.
Does the Supabase MCP server work with ChatGPT?
It is a hosted server that signs in with OAuth, so you can add https://mcp.supabase.com/mcp as a custom MCP server on chatgpt.com/plugins. Supabase's own guides focus on coding tools such as Claude Code and Cursor.
What does project_ref do?
It limits the server to one project and turns off the account-level tools, so the assistant cannot list or touch your other projects. Without it, every project in the organisation you sign in with is reachable.
Can I use the Supabase MCP server with a local Supabase stack?
Yes. The Supabase CLI serves it at http://localhost:54321/mcp while your local stack runs. It offers a smaller set of tools and no OAuth, which is fine for local development.
Supabase MCP or Postgres MCP Pro?
Pick Supabase's server to manage a Supabase project end to end: SQL, migrations, branches, edge functions and logs. Pick Postgres MCP Pro to tune any Postgres database, with index advice and health checks.
Supabase README
This is the project's own README from supabase-community/supabase-mcp, written by Supabase, and shared under its Apache-2.0 licence. We copied it on 27 Oct 2026, so the version on GitHub may be newer.
Supabase MCP Server
Connect your Supabase projects to Cursor, Claude, Windsurf, and other AI assistants.
The Model Context Protocol (MCP) standardizes how Large Language Models (LLMs) talk to external services like Supabase. It connects AI assistants directly with your Supabase project and allows them to perform tasks like managing tables, fetching config, and querying data. See the full list of tools.
Setup
1. Follow our security best practices
Before setting up the MCP server, we recommend you read our security best practices to understand the risks of connecting an LLM to your Supabase projects and how to mitigate them.
2. Configure your MCP client
To configure the Supabase MCP server on your client, visit our setup documentation. You can also generate a custom MCP URL for your project by visiting the MCP connection tab in the Supabase dashboard.
Your MCP client will automatically prompt you to log in to Supabase during setup. Be sure to choose the organization that contains the project you wish to work with.
Most MCP clients require the following information:
{
"mcpServers": {
"supabase": {
"type": "http",
"url": "https://mcp.supabase.com/mcp"
}
}
}
If you don't see your MCP client listed in our documentation, check your client's MCP documentation and copy the above MCP information into their expected format (json, yaml, etc).
CLI
If you're running Supabase locally with Supabase CLI, you can access the MCP server at http://localhost:54321/mcp. Currently, the MCP Server in CLI environments offers a limited subset of tools and no OAuth 2.1.
Self-hosted
For self-hosted Supabase, check the Enabling MCP server page. Currently, the MCP Server in self-hosted environments offers a limited subset of tools and no OAuth 2.1.
Configuration options and tools
See the Supabase MCP Server docs for the full list of available tools and configuration options.
The docs also feature an interactive URL builder to populate configuration options for you.
Usage with AI SDK's MCP Client
The @supabase/mcp-server-supabase package exports createToolSchemas() to populate input and output schemas for Vercel AI SDK's MCP client. This allows Supabase MCP tools to be treated as static tools with client-side validation and inferred TypeScript types for their inputs and outputs.
import { createToolSchemas } from '@supabase/mcp-server-supabase';
import { createMCPClient } from '@ai-sdk/mcp';
import { streamText } from 'ai';
const mcpClient = await createMCPClient({
transport: {
type: 'http',
url: 'https://mcp.supabase.com/mcp',
},
});
const tools = await mcpClient.tools({
schemas: createToolSchemas(),
});
const result = streamText({ model, tools, prompt: '...' });
for (const step of await result.steps) {
for (const toolResult of step.staticToolResults) {
if (toolResult.toolName === 'get_project_url') {
toolResult.input; // { project_id: string }
toolResult.output; // { url: string }
}
}
}
createToolSchemas() accepts similar filtering options as the MCP server's URL parameters:
features: Restrict to specific feature groups (e.g.['database', 'docs']). Defaults to all default feature groups.projectScoped: Whentrue, omitsproject_idfrom tool input schemas and excludes account-level tools — use when connecting to a server configured withproject_ref. Defaults tofalse.readOnly: Whentrue, excludes mutating tools — use when connecting to a server configured withread_only=true. Defaults tofalse.
const mcpClient = await createMCPClient({
transport: {
type: 'http',
url: 'https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs',
},
});
const tools = await mcpClient.tools({
schemas: createToolSchemas({
features: ['database', 'docs'],
projectScoped: true,
readOnly: true,
}),
});
Note: This server does not send
structuredContentin MCP tool results. AI SDK falls back to parsing JSON fromcontenttext.
For more information, see Schema Definition and Typed Tool Outputs in the AI SDK docs.
Self-hosting the MCP endpoint
The @supabase/mcp-server-supabase package exports createSupabaseMcpHandler() to serve the tools over HTTP from your own endpoint. It accepts the same SupabaseMcpServerOptions as createSupabaseMcpServer(), most importantly platform.
The handler speaks the current protocol revision only. It is created with legacy: 'reject', so a client that only speaks the 2025-era protocol receives an HTTP 400 instead of being served.
When platform carries a per-request credential, create the handler per request and close it when the response finishes. The handler closes over the platform you supply, so a shared one serves every request with that platform.
A long-lived handler is fine when the platform is meant to be shared, a service-account token for example. Create it once and close() it at shutdown rather than per response, since close() tears down the subscription router and refuses later requests.
import { createServer } from 'node:http';
import { toNodeHandler } from '@modelcontextprotocol/node';
import { createSupabaseMcpHandler } from '@supabase/mcp-server-supabase';
import { createSupabaseApiPlatform } from '@supabase/mcp-server-supabase/platform/api';
const server = createServer((req, res) => {
const accessToken = getAccessTokenFromRequest(req); // your own auth
const handler = createSupabaseMcpHandler({
platform: createSupabaseApiPlatform({ accessToken }),
});
// `close()` aborts in-flight exchanges, so close on `res` finishing rather
// than when the handler resolves, which would cut streaming responses short.
res.on('close', () => {
handler.close().catch((error) => console.error(error));
});
toNodeHandler(handler)(req, res).catch((error) => console.error(error));
});
toNodeHandler comes from @modelcontextprotocol/node. Your code imports it directly, so install it alongside.
Observability
Pass an observer to createSupabaseMcpServer to collect request lifecycle results and Supabase's built-in facts. Here, platform is your existing platform adapter:
import { createSupabaseMcpServer } from '@supabase/mcp-server-supabase';
const server = createSupabaseMcpServer({
platform,
observer: (context) => ({
record(fact) {
console.info(fact);
},
end(result) {
console.info({ ...context, ...result });
},
}),
});
The server does not automatically forward request or response payloads to the observer. Supabase's built-in facts use a closed set of bounded fields and values; custom facts receive no automatic privacy validation. Omitting observer skips all observation work. Observer, classifier and sink failures don't change request behavior, but synchronous observer and classifier work can block requests.
Other MCP servers
@supabase/mcp-server-postgrest
The PostgREST MCP server allows you to connect your own users to your app via REST API. See more details on its project README.
Resources
- Model Context Protocol: Learn more about MCP and its capabilities.
- From development to production: Learn how to safely promote changes to production environments.
For developers
See CONTRIBUTING for details on how to contribute to this project.
License
This project is licensed under Apache 2.0. See the LICENSE file for details.
Two peas, one chat
Chat with AI about Supabase
Opens a chat primed with Supabase’s README and setup docs from this page, or add it in Cursor to use its tools.
The Cursor button opens Cursor and asks before it adds the server. Fill in any keys it needs in Cursor’s MCP settings.
Peas in a pod
What are the alternatives to Supabase?
How Supabase lines up against its neighbours on the shelf. See every databases and data server.

SupabaseThis pea
Manage Supabase projects, tables, migrations, logs and Edge Functions.
- Tools
- 29
- Runs on
- Hosted
- Licence
- Apache-2.0
- Stars
- 3K
Google's toolbox for Postgres, MySQL, BigQuery, Spanner and other databases.
- Tools
- 29
- Runs on
- Your computer
- Licence
- Apache-2.0
- Stars
- 16.7K
Store notes and find them by meaning in a Qdrant vector collection.
- Tools
- 2
- Runs on
- Your computer
- Licence
- Apache-2.0
- Stars
- 1.6K

Create, edit, format and chart .xlsx files, no Excel needed.
- Tools
- 46
- Runs on
- Your computer
- Licence
- MIT
- Stars
- 4.3K

One small server for Postgres, MySQL, MariaDB, SQL Server, Oracle and SQLite.
- Tools
- 2
- Runs on
- Your computer
- Licence
- MIT
- Stars
- 3.7K

SQL, query plans, health checks and index advice for Postgres.
- Tools
- 9
- Runs on
- Your computer
- Licence
- MIT
- Stars
- 3.4K
Compared head to head: Postgres MCP Pro vs Supabase.
Something wrong on this page? Tell us.
For bots & AI agents
Machine-readable versions of Supabase and MCP Shelf. Fetch these instead of parsing this page.
This listing (.md)llms.txtllms-full.txtai.txtFull catalog (.md)API specMCP serverMCP manifestDeveloper docs