Getting Started

Model context protocol (MCP)

Connect your AI tools to Supabase using MCP

The Model Context Protocol (MCP) is a standard for connecting Large Language Models (LLMs) to platforms like Supabase. This guide covers how to connect Supabase to the following AI tools using MCP:

Once connected, your AI assistants can interact with and query your Supabase projects on your behalf.

Step 1: Create a personal access token (PAT)

First, go to your Supabase settings and create a personal access token. Give it a name that describes its purpose, like "Cursor MCP Server". This will be used to authenticate the MCP server with your Supabase account.

Step 2: Configure in your AI tool

MCP compatible tools can connect to Supabase using the Supabase MCP server. Below are instructions for connecting to this server using popular AI tools:

Cursor

  1. Open Cursor and create a .cursor directory in your project root if it doesn't exist.

  2. Create a .cursor/mcp.json file if it doesn't exist and open it.

  3. Add the following configuration:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": [        "-y",        "@supabase/mcp-server-supabase@latest",        "--access-token",        "<personal-access-token>"      ]    }  }}

    Replace <personal-access-token> with your personal access token.

  4. Save the configuration file.

  5. Open Cursor and navigate to Settings/MCP. You should see a green active status after the server is successfully connected.

Windsurf

  1. Open Windsurf and navigate to the Cascade assistant.

  2. Tap on the hammer (MCP) icon, then Configure to open the configuration file.

  3. Add the following configuration:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": [        "-y",        "@supabase/mcp-server-supabase@latest",        "--access-token",        "<personal-access-token>"      ]    }  }}

    Replace <personal-access-token> with your personal access token.

  4. Save the configuration file and reload by tapping Refresh in the Cascade assistant.

  5. You should see a green active status after the server is successfully connected.

Cline

  1. Open the Cline extension in VS Code and tap the MCP Servers icon.

  2. Tap Configure MCP Servers to open the configuration file.

  3. Add the following configuration:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": [        "-y",        "@supabase/mcp-server-supabase@latest",        "--access-token",        "<personal-access-token>"      ]    }  }}

    Replace <personal-access-token> with your personal access token.

  4. Save the configuration file. Cline should automatically reload the configuration.

  5. You should see a green active status after the server is successfully connected.

Claude desktop

  1. Open Claude desktop and navigate to Settings.

  2. Under the Developer tab, tap Edit Config to open the configuration file.

  3. Add the following configuration:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": [        "-y",        "@supabase/mcp-server-supabase@latest",        "--access-token",        "<personal-access-token>"      ]    }  }}

    Replace <personal-access-token> with your personal access token.

  4. Save the configuration file and restart Claude desktop.

  5. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available.

Claude code

  1. Create a .mcp.json file in your project root if it doesn't exist.

  2. Add the following configuration:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": [        "-y",        "@supabase/mcp-server-supabase@latest",        "--access-token",        "<personal-access-token>"      ]    }  }}

    Replace <personal-access-token> with your personal access token.

  3. Save the configuration file.

  4. Restart Claude code to apply the new configuration.

Next steps

Your AI tool is now connected to Supabase using MCP. Try asking your AI assistant to create a new project, create a table, or fetch project config.

For a full list of tools available, see the GitHub README. If you experience any issues, submit an bug report.

MCP for local Supabase instances

The Supabase MCP server connects directly to the cloud platform to access your database. If you are running a local instance of Supabase, you can instead use the Postgres MCP server to connect to your local database. This MCP server runs all queries as read-only transactions.

Step 1: Find your database connection string

To connect to your local Supabase instance, you need to get the connection string for your local database. You can find your connection string by running:

1
supabase status

or if you are using npx:

1
npx supabase status

This will output a list of details about your local Supabase instance. Copy the DB URL field in the output.

Step 2: Configure the MCP server

Configure your client with the following:

1
2
3
4
5
6
7
8
{  "mcpServers": {    "supabase": {      "command": "npx",      "args": ["-y", "@modelcontextprotocol/server-postgres", "<connection-string>"]    }  }}

Replace <connection-string> with your connection string.

Next steps

Your AI tool is now connected to your local Supabase instance using MCP. Try asking the AI tool to query your database using natural language commands.