Getting Started

Model context protocol (MCP)

The Model Context Protocol (MCP) is a standard for connecting Large Language Models (LLMs) to external services.

This guide covers how to connect Supabase to the following AI tools using MCP:

Once connected, you can use natural language commands to run read-only database queries in the AI tool.

Connect to Supabase using MCP

Supabase uses the Postgres MCP server to provide MCP access to your database. The MCP server runs all queries as read-only transactions.

Step 1: Find your database connection string

To get started, you will need to retrieve your database connection string. These will differ depending on whether you are using a hosted or local instance of Supabase.

For a hosted Supabase instance

Connection string (pooler session mode)

Log in and choose a project above to find your connection string, or find it in the Dashboard:

  1. Navigating to your project's Connection settings
  2. Copying the connection string found under Session pooler.

For a local Supabase instance

When running a local instance of Supabase via the CLI, 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 in your AI tool

MCP compatible tools can connect to Supabase using the Postgres MCP server. Below are instructions on to connect to the Postgres MCP 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
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": ["-y", "@modelcontextprotocol/server-postgres", "<connection-string>"]    }  }}

    Replace <connection-string> with your connection string.

  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
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": ["-y", "@modelcontextprotocol/server-postgres", "<connection-string>"]    }  }}

    Replace <connection-string> with your connection string.

  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
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": ["-y", "@modelcontextprotocol/server-postgres", "<connection-string>"]    }  }}

    Replace <connection-string> with your connection string.

  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
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": ["-y", "@modelcontextprotocol/server-postgres", "<connection-string>"]    }  }}

    Replace <connection-string> with your connection string.

  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
    {  "mcpServers": {    "supabase": {      "command": "npx",      "args": ["-y", "@modelcontextprotocol/server-postgres", "<connection-string>"]    }  }}

    Replace <connection-string> with your connection string.

  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 the AI tool to query your database using natural language commands.