supabase-mcp-server 0.3.0

Unofficial MCP server for Supabase providing basic schema, table, and column management.

Supabase MCP Server

  

Let Cursor & Windsurf interact with Supabase autonomously

Unofficial feature-rich Supabase MCP server that enables Cursor and Windsurf to manage your database, execute SQL queries, and use every method and object in Python SDK.

✨ Key features

• 💻 Compatible with Cursor, Windsurf, Cline and other MCP clients supporting stdio protocol
• 🔐 Control read-only and read-write modes of SQL query execution
• 💻 Manage your Supabase projects with Supabase Management API
• 🔨 Pre-built tools to help Cursor & Windsurf work with MCP more effectively
• 📦 Dead-simple install & setup via package manager (uv, pipx, etc.)

Prerequisites

• Python 3.12+
• PostgreSQL 16+
• uv package manager

PostgreSQL Installation

⚠️ Important: PostgreSQL must be installed BEFORE installing project dependencies, as psycopg2 requires PostgreSQL development libraries during compilation.

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

MCP Server Installation

⚠️ 0.2.0 Breaking change: Installation and execution methods have changed to support package distribution. The server now runs as a proper Python module instead of a direct script.

You can install Supabase MCP Server either using a package manager (recommended) or from source (just as in v0.1.0).

Using Package Managers (Recommended)

Choose the installation method based on your needs:

# Using pipx (recommended for CLI tools)
pipx install supabase-mcp-server
# → Run with: supabase-mcp-server

# Using UV (if you prefer your current environment)
uv pip install supabase-mcp-server
# → Run with: uv run supabase-mcp-server

Why these package managers?

• pipx:

  • Creates isolated environments for CLI tools
  • Makes commands globally available as supabase-mcp-server
  • Prevents dependency conflicts
  • Best for end users who just want to use the tool

• uv:

  • Installs in your current environment
  • Faster installation and dependency resolution
  • Requires uv run prefix to execute
  • Better for development or if you're using uv for other packages

Installing from Source

1. Clone the repository

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

2. Create and activate virtual environment

# Create venv
uv venv

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

3. Install in editable mode

uv pip install -e .

Installing via Smithery

Please report any issues with Smithery, as I haven't tested it yet.

To install Supabase MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @alexander-zuev/supabase-mcp --client claude

Running Supabase MCP Server

This MCP server was designed to be used with AI IDEs like Cursor and Windsurf and not tested with other clients. However, it should work with any MCP-compatible IDE as long as it uses stdio protocol.

You can run the server in several ways:

• as a package script (if you installed it using package manager)
• as a python module (if you installed it from source)

💡 0.2.0 Breaking change: Installation and execution methods have changed to support package distribution. The server now runs as a proper Python module instead of a direct script:

• Old: uv --directory /path/to/supabase-mcp-server run main.py
• New: uv run supabase-mcp-server (if installed via package manager)
• New: uv --directory /path/to/supabase-mcp-server run python -m supabase_mcp.main (if installed from source)

Running as a package script (if you installed it using package manager)

If you installed it using package manager, you can run the server with this command:

# Pipx
supabase-mcp-server

# UV
uv run supabase-mcp-server

Setup Cursor

⚠️ Important: Unlike Windsurf's defacto standard JSON configuration, Cursor team had a 'genius' idea to abstract away the underlying configuration into a barebones, poorly documented UI (took me several hours to figure out how to set it up) 😡. So in order to connect to a remote Supabase project, you need to set environment variables globally. I've provided a way to pick up .env file from a global config directory (~/.config/supabase-mcp/.env on macOS/Linux or %APPDATA%\supabase-mcp\.env on Windows).

1. Set up global config (recommended approach):

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

# Create and open .env file
# On macOS/Linux
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1  # optional, defaults to us-east-1" > .env && open .
# On Windows (in PowerShell)
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1  # optional, defaults to us-east-1" > .env ; explorer .

2. Create a new MCP server in Cursor:

name: supabase
protocol: command
# if pipx (recommended)
command: supabase-mcp-server
# if uv
command: uv run supabase-mcp-server

3. Reload Cursor If you encounter connection issues, try closing and reopening Cursor.

Setup Windsurf

💡 Setting environment variables: For Windsurf, it's recommended to set environment variables directly in the mcp_config.json as shown below.

1. Add / modify mcp_config.json file:

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/your-username/.local/bin/supabase-mcp-server",
        "env": {
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1"  // optional, defaults to us-east-1
        }
      }
    }
}

Don't forget to replace your-username with your actual username. You can find where it's located by running which supabase-mcp-server in terminal.

💡 Finding Supabase MCP Server executable path:

• On macOS/Linux: Run which supabase-mcp-server in terminal
• On Windows: Run where supabase-mcp-server in command prompt The output will show the full path to use in your configuration.

Running as a python module (if you installed it from source)

If you installed from source or want to run the development version, use this command:

uv --directory /path/to/supabase-mcp-server run python -m supabase_mcp.main

Setup Cursor

1. Create a new MCP server
2. Add the following configuration:

name: supabase
protocol: command
command: uv --directory /path/to/supabase-mcp-server run python -m supabase_mcp.main

Replace /path/to/supabase-mcp-server with your actual repository path, for example:

command: uv --directory /Users/username/projects/supabase-mcp-server run python -m supabase_mcp.main

Setup Windsurf

1. Add / modify mcp_config.json file:

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/az/.local/bin/uv",
        "args": [
          "--directory",
          "/path/to/supabase-mcp-server",
          "run",
          "python",
          "-m",
          "supabase_mcp.main"
        ],
        "env": {
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1"  // optional, defaults to us-east-1
        }
      }
    }
}

Configuring connection to different Supabase projects

💡 Tip: Connection to local Supabase project is configured out of the box. You don't need to set environment variables.

To connect to a different Supabase project, you need to set environment variables:

• SUPABASE_PROJECT_REF
• SUPABASE_DB_PASSWORD
• SUPABASE_REGION (optional, defaults to us-east-1)

The server supports all Supabase regions:

• us-west-1 - West US (North California)
• us-east-1 - East US (North Virginia) - default
• us-east-2 - East US (Ohio)
• ca-central-1 - Canada (Central)
• eu-west-1 - West EU (Ireland)
• eu-west-2 - West Europe (London)
• eu-west-3 - West EU (Paris)
• eu-central-1 - Central EU (Frankfurt)
• eu-central-2 - Central Europe (Zurich)
• eu-north-1 - North EU (Stockholm)
• ap-south-1 - South Asia (Mumbai)
• ap-southeast-1 - Southeast Asia (Singapore)
• ap-northeast-1 - Northeast Asia (Tokyo)
• ap-northeast-2 - Northeast Asia (Seoul)
• ap-southeast-2 - Oceania (Sydney)
• sa-east-1 - South America (São Paulo)

The recommended way to set these variables depends on your IDE:

• For Windsurf: Set them directly in mcp_config.json (cleanest approach)
• For Cursor: Set them using global config directory (see Setup Cursor)
• For local development: Use .env in the project root (when installed from source)

Local Supabase project

If no configuration is provided, the server defaults to local Supabase settings:

• Host: 127.0.0.1:54322
• Password: postgres

This works out of the box with Supabase CLI's local development setup.

Remote Supabase project (staging / production)

When using Windsurf

Set the environment variables directly in your mcp_config.json:

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/your-username/.local/bin/supabase-mcp-server",
        "env": {
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1"  // optional, defaults to us-east-1
        }
      }
    }
}

💡 Finding Supabase MCP Server executable path:

• On macOS/Linux: Run which supabase-mcp-server in terminal
• On Windows: Run where supabase-mcp-server in command prompt The output will show the full path to use in your configuration.

When using Cursor

Create a global config file:

# Create config directory and navigate to it
# On macOS/Linux
mkdir -p ~/.config/supabase-mcp && cd ~/.config/supabase-mcp
# On Windows (in PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp" ; cd "$env:APPDATA\supabase-mcp"

# Create and open .env file
# On macOS/Linux
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1  # optional, defaults to us-east-1" > .env && open .
# On Windows (in PowerShell)
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1  # optional, defaults to us-east-1" > .env ; explorer .

Then in Cursor's MCP server configuration:

name: supabase
protocol: command
# if pipx (recommended)
command: supabase-mcp-server
# if uv
command: uv run supabase-mcp-server

💡 Note: Unlike Windsurf, Cursor requires configuration via global config file or environment variables. The global config approach is recommended for better maintainability.

Global config

3. Global config (Lowest precedence)

   # Create in your home config directory for persistent access
   mkdir -p ~/.config/supabase-mcp
   echo "SUPABASE_PROJECT_REF=your-project-ref
   SUPABASE_DB_PASSWORD=your-db-password
   SUPABASE_REGION=us-east-1  # optional, defaults to us-east-1" > ~/.config/supabase-mcp/.env
   

   Perfect for developers who want to set up once and use across multiple projects.

When developing locally (installed from source)

Create .env file in the root of the cloned repository:

# In the supabase-mcp-server directory (project root)
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1  # optional, defaults to us-east-1" > .env

When running from source, it looks for .env in the project root directory (where you cloned the repository).

How to troubleshoot common issues?

Here are some tips & tricks that might help you:

• Debug installation - run supabase-mcp-server directly from the terminal to see if it works. If it doesn't, there might be an issue with the installation.
• MCP Server configuration - if the above step works, it means the server is installed and configured correctly. As long as you provided the right command IDE should be able to connect. Make sure to provide the right path to the server executable.
• Environment variables - to connect to the right database, make sure you either set env variables in mcp_config.json or in .env file placed in a global config directory (~/.config/supabase-mcp/.env on macOS/Linux or %APPDATA%\supabase-mcp\.env on Windows). The required variables are SUPABASE_PROJECT_REF and SUPABASE_DB_PASSWORD, with optional SUPABASE_REGION (defaults to us-east-1).

Feature overview

Supabase Connection Configuration

Configuration of the connection to the Supabase project is done via environment variables.

• Supports all 16 Supabase regions
• Can be set in mcp_config.json, .env file or globally in ~/.config/supabase-mcp/.env
• For local development, the server defaults to local Supabase settings:
  • Host: 127.0.0.1:54322
  • Password: postgres
• For remote development, you need to set the environment variables directly in mcp_config.json or in .env file.
  • SUPABASE_PROJECT_REF - your project ref (e.g. project-ref)
  • SUPABASE_DB_PASSWORD - your database password
  • SUPABASE_REGION - optional, defaults to us-east-1

SQL query execution

As of v0.3, the server supports both read-only and read-write SQL queries.

• Supported modes:
  • read-only - only read-only queries are allowed (default mode)
  • read-write - all SQL operations are allowed when explicitly enabled
• Safety features:
  • Starts in read-only mode by default
  • Requires explicit mode switch for write operations
  • Automatically resets to read-only mode after write operations
  • Uses transactions to ensure clean state in tests
• SQL query validation [TODO]

Supabase Management API

Introduced in v0.2.3, the server supports sending arbitrary requests to Supabase Management API with auto-injection of project ref and safety mode control:

• Includes the following tools:
  • send_management_api_request to send arbitrary requests to Supabase Management API, with auto-injection of project ref and safety mode control.
  • get_management_api_spec to get the enriched API specification with safety information
  • get_management_api_safety_rules to get all safety rules including blocked and unsafe operations with human-readable explanations
  • live_dangerously to switch to yolo mode
• Safety features:
  • Divides API methods into safe, unsafe and blocked categories based on the risk of the operation
  • Allows to switch between safe and yolo modes dynamically
  • Blocked operations (delete project, delete database) are not allowed regardless of the mode

Support of Python SDK methods

Future versions will include support for the following Python SDK methods

Connect to Supabase logs

Future versions will include a tool to connect to Supabase logs to help debug errors.

Future improvements

• 📦 Simplified installation via package manager - ✅ (0.2.0)
• 🌎 Support for different Supabase regions - ✅ (0.2.2)
• 🐍 Support methods and objects available in native Python SDK
• 👷‍♂️ Safe running of non read-only SQL queries
• 🎮 Programmatic access to Supabase management API
• 🔍 Strong SQL query validation
• 📝 Connect to db logs to help debug errors