Supercharge Your AI with Supabase: The Model Context Protocol Server

Seamlessly connect your Supabase projects to AI assistants like Cursor, Claude, and Windsurf using the Model Context Protocol.

supabase-mcp-demo

The Model Context Protocol (MCP) is revolutionizing how Large Language Models (LLMs) interact with external services. This supabase-mcp-server acts as a bridge, directly linking your AI assistants to your Supabase project, enabling them to perform a wide range of tasks, from managing database schemas to querying data and fetching configurations. Explore the comprehensive list of available tools below.

Getting Started: Prerequisites

Before diving in, ensure you have Node.js installed. Verify your installation by running:

node -v

If Node.js is not installed, download the latest version from nodejs.org.

Step-by-Step Setup

1. Generate a Personal Access Token (PAT)

Navigate to your Supabase account settings and create a new Personal Access Token (PAT). Assign a descriptive name, such as "Cursor MCP Server," to easily identify its purpose.

This PAT will authenticate the MCP server with your Supabase account. Important: Copy the token immediately, as it will not be visible again.

2. Configure Your MCP Client

Configure your MCP client (e.g., Cursor) to utilize this server. Most clients accept configuration in JSON format, structured as follows:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--access-token",
        "<personal-access-token>"
      ]
    }
  }
}

Replace <personal-access-token> with the PAT you generated in the previous step. Alternatively, for enhanced security, you can omit the --access-token argument and set the SUPABASE_ACCESS_TOKEN environment variable. Remember to restart your MCP client after setting the environment variable. This approach prevents the token from being stored in version control.

For Windows users, special instructions apply (see Windows Configuration). If your MCP client does not support JSON configuration, use the following direct CLI command:

npx -y @supabase/mcp-server-supabase@latest --access-token=<personal-access-token>

Important: This command is intended to be executed by your MCP client to initiate the server, not directly in your terminal. npx automatically downloads and runs the latest version of the MCP server from npm.

Windows Configuration

On Windows, you'll need to prefix the command with cmd /c or wsl, depending on your environment:

Using cmd /c:

{
  "mcpServers": {
    "supabase": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--access-token",
        "<personal-access-token>"
      ]
    }
  }
}

Using wsl (if Node.js is running inside WSL):

{
  "mcpServers": {
    "supabase": {
      "command": "wsl",
      "args": [
        "npx",
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--access-token",
        "<personal-access-token>"
      ]
    }
  }
}

Ensure Node.js is accessible in your system's PATH environment variable. If running Node.js natively on Windows, follow these steps:

Get the path to npm:
```
npm config get prefix
```
Add the directory to your PATH:
```
setx PATH "%PATH%;<path-to-dir>"
```
Restart your MCP client.

Enabling Read-Only Mode

To restrict the Supabase MCP server to read-only queries, use the --read-only flag:

npx -y @supabase/mcp-server-supabase@latest --access-token=<personal-access-token> --read-only

This executes SQL queries as a read-only Postgres user, preventing write operations on your databases. This flag applies specifically to database tools (execute_sql and apply_migration) and does not affect other tools like create_project or create_branch.

Available Tools

Important Note: This server is currently pre-1.0, and breaking changes may occur between versions. However, LLMs should automatically adapt to the available tools, minimizing disruption.

The following Supabase tools are exposed to the LLM:

Project Management

list_projects: Retrieves a list of all Supabase projects associated with the user.
get_project: Fetches detailed information for a specific project.
create_project: Creates a new Supabase project.
pause_project: Pauses an existing project.
restore_project: Restores a paused project.
list_organizations: Lists all organizations the user is a member of.
get_organization: Retrieves details for a specific organization.

Database Operations

list_tables: Lists all tables within specified schemas.
list_extensions: Lists all extensions installed in the database.
list_migrations: Lists all migrations applied to the database.
apply_migration: Applies a SQL migration to the database. Crucially, SQL passed to this tool is tracked within the database, making it ideal for DDL operations (schema modifications).
execute_sql: Executes raw SQL queries against the database. LLMs should use this for standard queries that do not alter the schema.
get_logs: Retrieves logs for a Supabase project, categorized by service type (api, postgres, edge functions, auth, storage, realtime). This is invaluable for debugging and monitoring service performance.

Project Configuration

get_project_url: Retrieves the API URL for a project.
get_anon_key: Retrieves the anonymous API key for a project.

Branching (Experimental, Requires a Paid Plan)

create_branch: Creates a development branch, inheriting migrations from the production branch.
list_branches: Lists all existing development branches.
delete_branch: Deletes a development branch.
merge_branch: Merges migrations and edge functions from a development branch into the production environment.
reset_branch: Resets the migrations of a development branch to a previous state.
rebase_branch: Rebases a development branch onto the production branch to resolve migration drift.

Development Tools

generate_typescript_types: Generates TypeScript type definitions based on the database schema. LLMs can save this to a file and leverage it within their code.

Cost Confirmation

get_cost: Retrieves the estimated cost of creating a new project or branch for an organization.
confirm_cost: Requires user confirmation of the estimated costs before creating a new project or branch.

Explore Other MCP Servers

`@supabase/mcp-server-postgrest`

The PostgREST MCP server enables you to connect your own users to your application via a REST API. Refer to the project README for detailed information.

Essential Resources

Model Context Protocol: Deepen your understanding of MCP and its capabilities.

supabase-mcp