Supabase MCP Server

Let Cursor & Windsurf interact with Supabase

Implementaton of Supabase MCP server that enables Cursor and Windsurf to interact directly with Supabase PostgreSQL database. It provides a set of database management tools that work seamlessly with these IDEs through the MCP protocol.

Key features

💻 Works with both Windsurf and Cursor IDEs
✅ Supports local Supabase projects and production Supabase projects
🔨 Built-in database exploration tools with schema insights
🔐 Secure read-only database access
🔍 SQL query validation

Prerequisites

Python 3.12+
PostgreSQL 16+
uv package manager

Mac-specific Setup

PostgreSQL Installation (Required for psycopg2)
```
brew install postgresql@16
```
⚠️ Important: PostgreSQL must be installed BEFORE installing project dependencies. The psycopg2 package requires PostgreSQL development libraries during compilation.
uv Package Manager
```
pip install uv
```

Windows Setup

PostgreSQL Installation
- Download and install PostgreSQL 16+ from https://www.postgresql.org/download/windows/
- Ensure "PostgreSQL Server" and "Command Line Tools" are selected during installation
uv Package Manager
```
pip install uv
```

Installation

Clone and setup environment

git clone https://github.com/alexander-zuev/supabase-mcp-server.git
cd supabase-mcp-server

# Create and activate virtual environment
uv venv

# Mac/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

Install dependencies

uv sync

📝 If you get psycopg2 compilation errors, make sure you've installed PostgreSQL first!

Usage

Local Development

MCP server connects to your local Supabase project by default:

Host: 127.0.0.1:54322
Password: postgres

Production Setup

For staging or production Supabase projects, set these environment variables (setup differs for Cursor and Windsurf):

SUPABASE_PROJECT_REF="your-project-ref"  # e.g., "abcdefghijklm"
SUPABASE_DB_PASSWORD="your-db-password"

Cursor Setup

Add an MCP server with this configuration:

name: supabase
protocol: stdio
command: uv --directory /path/to/cloned/supabase-mcp-server run main.py

Example with actual path:

command: uv --directory /Users/az/cursor/supabase-mcp-server run main.py

After adding this configuration, Agent mode will have access to all database tools.

Windsurf

Windsurf relies on a 'Claude Desktop' like configuration to connect to MCP server. This means you need to edit mcp_config.json file to connect to MCP server:

{
  "mcpServers": {
    "supabase": {
      "command": "/Users/az/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/username/cursor/supabase-mcp-server",  // Your repository path
        "run",
        "main.py"
      ],
      "env": {
        "SUPABASE_PROJECT_REF": "127.0.0.1:54322",  // Local development default
        "SUPABASE_DB_PASSWORD": "postgres"  // Local development default
      }
    }
  }
}

After saving and refreshing, Cascade will have access to all database tools.

Development

Start the development server

mcp dev main.py

Start your local Supabase instance

supabase start

Future improvements

🐍 Support methods and objects available in native Python SDK
🔍 Improve SQL syntax validation

Supabase MCP Server