Supabase MCP server

This MCP server enables secure interaction between Cursor and Windsurf AI coding assistants and Supabase databases, allowing them to safely execute SQL queries and manage your database resources with built-in safety controls.

Installation

Prerequisites

Before installing, ensure you have:

• Python 3.12+
• PostgreSQL 16+

PostgreSQL must be installed before installing the MCP server as it requires PostgreSQL development libraries.

PostgreSQL Installation:

MacOS:

brew install postgresql@16

Windows:

• Download and install PostgreSQL 16+ from https://www.postgresql.org/download/windows/
• Ensure "PostgreSQL Server" and "Command Line Tools" are selected during installation

Installing the MCP Server

Install using a package manager:

# Recommended: using pipx (for isolated environment)
pipx install supabase-mcp-server

# Alternative: using uv
uv pip install supabase-mcp-server

Configuration

The server requires configuration to connect to your Supabase instance.

Local Supabase Instance (Default)

The server is pre-configured for local Supabase with default settings:

• Host: 127.0.0.1:54322
• Password: postgres

No additional configuration needed for local instances with default settings.

Remote Supabase Instance

For remote Supabase projects, configure these variables:

SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1  # optional, defaults to us-east-1
SUPABASE_ACCESS_TOKEN=your-access-token  # optional, for management API

Find your SUPABASE_PROJECT_REF from your project's dashboard URL: https://supabase.com/dashboard/project/<supabase-project-ref>

Environment Variables Setup

For Cursor

Two options for configuration:

Project-specific configuration:

1. Create .cursor folder in your repo (if it doesn't exist)
2. Create or update mcp.json file:

   {
     "mcpServers": {
       "filesystem": {
         "command": "supabase-mcp-server"
       }
     }
   }
   

3. Create .env file in your project with your Supabase connection details

Global configuration:

1. Create config directory:

   # On macOS/Linux
   mkdir -p ~/.config/supabase-mcp
   
   # On Windows (PowerShell)
   mkdir -Force "$env:APPDATA\supabase-mcp"
   

2. Create and edit .env file:

   # On macOS/Linux
   nano ~/.config/supabase-mcp/.env
   
   # On Windows
   notepad "$env:APPDATA\supabase-mcp\.env"
   

3. Add your Supabase connection details:

   SUPABASE_PROJECT_REF=your-project-ref
   SUPABASE_DB_PASSWORD=your-db-password
   SUPABASE_REGION=us-east-1
   SUPABASE_ACCESS_TOKEN=your-access-token
   

For Windsurf

Create or update mcp_config.json file:

{
    "mcpServers": {
      "supabase": {
        "command": "/path/to/supabase-mcp-server",
        "env": {
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",
          "SUPABASE_ACCESS_TOKEN": "your-access-token"
        }
      }
    }
}

Find the server path with:

• macOS/Linux: which supabase-mcp-server
• Windows: where supabase-mcp-server

Connecting to MCP Server

In Cursor

1. Go to Settings → Features → MCP Servers
2. Add a new server with:

   name: supabase
   type: command
   command: supabase-mcp-server
   

If configured correctly, you'll see a green dot indicator and available tools.

In Windsurf

1. Go to Cascade → Click hammer icon → Configure
2. Fill in the configuration as shown in the previous section
3. When configured correctly, you'll see a green dot indicator for the Supabase server

Usage

Database Queries

The server supports both read-only and data modification operations:

Read-Only Operations (Default)

SELECT * FROM my_table WHERE id = 123;

Data Modification (Requires read-write mode)

Enable write access first with the live_dangerously tool, then execute:

BEGIN;
INSERT INTO my_table (name, description) VALUES ('New item', 'Description');
COMMIT;

Transaction Support

Recommended approach for changes:

BEGIN;
CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);
COMMIT;

Database Tools

• get_db_schemas - List all database schemas with sizes and table counts
• get_tables - List all tables in a schema with metadata
• get_table_schema - Get detailed table structure including columns and keys
• execute_sql_query - Execute SQL queries with comprehensive support for all operations

Management API Tools

• send_management_api_request - Send requests to Supabase Management API
• get_management_api_spec - Get API specification with safety information
• get_management_api_safety_rules - Get safety rules for operations
• live_dangerously - Switch between safe and unsafe modes

Auth Admin Tools

• get_auth_admin_methods_spec - Get documentation for Auth Admin methods
• call_auth_admin_method - Call Auth Admin methods (create users, generate links, etc.)

Troubleshooting

If you encounter issues:

1. Run supabase-mcp-server directly in terminal to verify installation
2. Check your environment variables and .env file placement
3. View logs at:
   • macOS/Linux: ~/.local/share/supabase-mcp/mcp_server.log
   • Windows: %USERPROFILE%\.local\share\supabase-mcp\mcp_server.log

Check logs with:

# On macOS/Linux
cat ~/.local/share/supabase-mcp/mcp_server.log

# On Windows (PowerShell)
Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.