Query | MCP server for Supabase

🌅 More than 17k installs via pypi and close to 30k downloads on Smithery.ai — in short, this was fun! 🥳 Thanks to everyone who has been using this server for the past few months, and I hope it was useful for you. Since Supabase has released their own official MCP server, I've decided to no longer actively maintain this one. The official MCP server is as feature-rich, and many more features will be added in the future. Check it out!

Table of contents

✨ 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
• 🔍 Runtime SQL query validation with risk level assessment
• 🛡️ Three-tier safety system for SQL operations: safe, write, and destructive
• 🔄 Robust transaction handling for both direct and pooled database connections
• 📝 Automatic versioning of database schema changes
• 💻 Manage your Supabase projects with Supabase Management API
• 🧑‍💻 Manage users with Supabase Auth Admin methods via Python SDK
• 🔨 Pre-built tools to help Cursor & Windsurf work with MCP more effectively
• 📦 Dead-simple install & setup via package manager (uv, pipx, etc.)

Getting Started

Prerequisites

Installing the server requires the following on your system:

• Python 3.12+

If you plan to install via uv, ensure it's installed.

PostgreSQL Installation

PostgreSQL installation is no longer required for the MCP server itself, as it now uses asyncpg which doesn't depend on PostgreSQL development libraries.

However, you'll still need PostgreSQL if you're running a local Supabase instance:

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

Step 1. Installation

Since v0.2.0 I introduced support for package installation. You can use your favorite Python package manager to install the server via:

# if pipx is installed (recommended)
pipx install supabase-mcp-server

# if uv is installed
uv pip install supabase-mcp-server

pipx is recommended because it creates isolated environments for each package.

You can also install the server manually by cloning the repository and running pipx install -e . from the root directory.

#### Installing from source If you would like to install from source, for example for local development:

uv venv
# On Mac
source .venv/bin/activate
# On Windows
.venv\Scripts\activate
# Install package in editable mode
uv pip install -e .

#### Installing via Smithery.ai

You can find the full instructions on how to use Smithery.ai to connect to this MCP server here.

Step 2. Configuration

The Supabase MCP server requires configuration to connect to your Supabase database, access the Management API, and use the Auth Admin SDK. This section explains all available configuration options and how to set them up.

🔑 Important: Since v0.4 MCP server requires an API key which you can get for free at thequery.dev to use this MCP server.

#### Environment Variables

The server uses the following environment variables:

Note: The default values are configured for local Supabase development. For remote Supabase projects, you must provide your own values for SUPABASE_PROJECT_REF and SUPABASE_DB_PASSWORD.

🚨 CRITICAL CONFIGURATION NOTE: For remote Supabase projects, you MUST specify the correct region where your project is hosted using SUPABASE_REGION. If you encounter a "Tenant or user not found" error, this is almost certainly because your region setting doesn't match your project's actual region. You can find your project's region in the Supabase dashboard under Project Settings.

#### Connection Types

##### Database Connection

• The server connects to your Supabase PostgreSQL database using the transaction pooler endpoint
• Local development uses a direct connection to 127.0.0.1:54322
• Remote projects use the format: postgresql://postgres.[project_ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

⚠️ Important: Session pooling connections are not supported. The server exclusively uses transaction pooling for better compatibility with the MCP server architecture.

##### Management API Connection

• Requires SUPABASE_ACCESS_TOKEN to be set
• Connects to the Supabase Management API at https://api.supabase.com
• Only works with remote Supabase projects (not local development)

##### Auth Admin SDK Connection

• Requires SUPABASE_SERVICE_ROLE_KEY to be set
• For local development, connects to http://127.0.0.1:54321
• For remote projects, connects to https://[project_ref].supabase.co

#### Configuration Methods

The server looks for configuration in this order (highest to lowest priority):

1. Environment Variables: Values set directly in your environment
2. Local .env File: A .env file in your current working directory (only works when running from source)
3. Global Config File:

• Windows: %APPDATA%\supabase-mcp\.env
• macOS/Linux: ~/.config/supabase-mcp/.env

1. Default Settings: Local development defaults (if no other config is found)

⚠️ Important: When using the package installed via pipx or uv, local .env files in your project directory are not detected. You must use either environment variables or the global config file.

#### Setting Up Configuration

##### Option 1: Client-Specific Configuration (Recommended)

Set environment variables directly in your MCP client configuration (see client-specific setup instructions in Step 3). Most MCP clients support this approach, which keeps your configuration with your client settings.

##### Option 2: Global Configuration

Create a global .env configuration file that will be used for all MCP server instances:

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

# Create and edit .env file
# On macOS/Linux
nano ~/.config/supabase-mcp/.env
# On Windows (PowerShell)
notepad "$env:APPDATA\supabase-mcp\.env"

Add your configuration values to the file:

QUERY_API_KEY=your-api-key
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1
SUPABASE_ACCESS_TOKEN=your-access-token
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

##### Option 3: Project-Specific Configuration (Source Installation Only)

If you're running the server from source (not via package), you can create a .env file in your project directory with the same format as above.

#### Finding Your Supabase Project Information

• Project Reference: Found in your Supabase project URL: https://supabase.com/dashboard/project/<project-ref>
• Database Password: Set during project creation or found in Project Settings → Database
• Access Token: Generate at https://supabase.com/dashboard/account/tokens