Skip to content
MCP Shelf

Supabase MCP Server

Manage Supabase projects, tables, migrations, logs and Edge Functions.

View on GitHub
  • 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).
MCP Shelf tests: numbers from our own runs, not the README · tested on 26 Oct 2026

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.

ToolWhat it is for
execute_sqlRuns a SQL query against the project's Postgres database and returns the rows.

Changes things10 tools · Can create, edit, send or delete.

ToolWhat it is for
apply_migrationRuns a schema change as a named migration so it is tracked like any other.
create_branchSpins up a development branch of a project to try changes safely.
create_projectStarts a new Supabase project in the organisation and region you choose.
delete_branchRemoves a development branch you no longer need.
deploy_edge_functionUploads and deploys an Edge Function from code the agent wrote.
merge_branchMerges a branch's migrations and functions back into production.
pause_projectPauses a project so it stops running.
rebase_branchBrings a branch up to date with migrations added to production since it was made.
reset_branchRolls a branch's migrations back to an earlier version.
restore_projectWakes a paused project up again.

Only reads18 tools · Looks things up and changes nothing.

ToolWhat it is for
confirm_costAsks you to accept the price before a new project or branch is created.
generate_typescript_typesBuilds TypeScript types from the current database schema.
get_advisorsLists security and performance warnings, such as tables missing row level security.
get_costTells you what a new project or branch would cost before you make it.
get_edge_functionFetches the source of one deployed Edge Function.
get_organizationShows one organisation's details and plan.
get_projectShows one project's details, region and status.
get_project_urlReturns the API URL your app uses to reach the project.
get_publishable_keysReturns the public keys a front end needs to talk to the project.
list_branchesLists a project's development branches and their state.
list_edge_functionsLists the Edge Functions deployed in a project.
list_extensionsShows which Postgres extensions are installed.
list_migrationsLists the migrations already applied to the database.
list_organizationsLists the organisations your account belongs to.
list_projectsLists every project you can reach.
list_tablesLists tables in the chosen schemas, with their columns.
query_logsPulls recent logs for the API, Postgres, auth, storage or functions to help debug.
search_docsSearches 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: When true, omits project_id from tool input schemas and excludes account-level tools — use when connecting to a server configured with project_ref. Defaults to false.
  • readOnly: When true, excludes mutating tools — use when connecting to a server configured with read_only=true. Defaults to false.
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 structuredContent in MCP tool results. AI SDK falls back to parsing JSON from content text.

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 Code
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.

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.

SettingWhat it does
https://mcp.supabase.com/mcpConfig · requiredThe hosted server address. Your client opens a Supabase sign-in the first time you connect.
project_refConfigAdd to the URL to lock the agent to one project. Account-wide tools such as creating projects disappear.?project_ref=abcdefghijklmnop
read_onlyConfigAdd read_only=true to the URL and every tool that changes data is left out.&read_only=true
featuresConfigComma-separated tool groups to switch on: account, database, debugging, development, docs, functions, branching, storage.&features=database,docs
http://localhost:54321/mcpConfigAddress 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.

supabase-mcp-demo

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: When true, omits project_id from tool input schemas and excludes account-level tools — use when connecting to a server configured with project_ref. Defaults to false.
  • readOnly: When true, excludes mutating tools — use when connecting to a server configured with read_only=true. Defaults to false.
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 structuredContent in MCP tool results. AI SDK falls back to parsing JSON from content text.

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

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
  • MCP Toolbox for Databases

    Google's toolbox for Postgres, MySQL, BigQuery, Spanner and other databases.

    Tools
    29
    Runs on
    Your computer
    Licence
    Apache-2.0
    Stars
    16.7K
  • Qdrant

    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
  • Excel MCP Server

    Create, edit, format and chart .xlsx files, no Excel needed.

    Tools
    46
    Runs on
    Your computer
    Licence
    MIT
    Stars
    4.3K
  • DBHub

    One small server for Postgres, MySQL, MariaDB, SQL Server, Oracle and SQLite.

    Tools
    2
    Runs on
    Your computer
    Licence
    MIT
    Stars
    3.7K
  • Postgres MCP Pro

    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.

Full docs on GitHubsupabase-community/supabase-mcp

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