supabase

This MCP server provides a Python-based implementation that lets your IDE safely run SQL against a Supabase database, manage schema changes with automatic versioning, and interact with Supabase services through built-in tools. It supports safe, read-only, read-write, and destructive operation modes, and exposes capabilities to call the Supabase Management API and use the Auth Admin SDK. The server is designed to work with standard MCP clients over the stdio protocol, so you can connect from editors like Cursor, Windsurf, or Cline.

To use the server, install it via pipx or uv as described in the installation guide, then configure the environment variables (project reference, database password, region, and API keys). Once running, you can execute SQL queries with safety checks, apply migrations automatically, fetch schema changes, and trigger Supabase Management API calls or Auth Admin SDK actions directly from your MCP client. The server enforces a three-tier safety system for SQL operations (safe, write, and destructive) to minimize risk when running potentially dangerous statements.

Prerequisites

• Python 3.12+ installed on your system
• Optional: uv tool installed if you prefer running via uv (see steps below)

Step 1: Install via uv (recommended for isolated envs)

• Ensure uv is installed, then install the MCP server package:

uv pip install supabase-mcp-server

• If you already have uv, you can also install using a direct uv command:

uv pip install supabase-mcp-server

Step 2: Install via pipx (recommended for isolation)

pipx install supabase-mcp-server

Step 3: Installing from source (for local development)

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

Step 4: Verify installation

# Check the server version or help
supabase-mcp-server --version

Step 5: Run locally with configuration Set required environment variables as described in the configuration section and start the server as per the chosen runtime (uvx or pipx).

Environment variables are critical for connecting to your Supabase project and API. Ensure SUPABASE_PROJECT_REF and SUPABASE_DB_PASSWORD are correct for remote projects, and SUPABASE_REGION matches your project region to avoid tenant/user errors. The server uses asyncpg for database access, and the Management API requires SUPABASE_ACCESS_TOKEN while the Auth Admin SDK requires SUPABASE_SERVICE_ROLE_KEY. If you encounter connection errors, double-check that your environment variables are loaded (e.g., proper .env file in the working directory) and that your network allows access to the Supabase endpoints. For local development, you can point the Auth Admin SDK to http://127.0.0.1:54321 or your remote project URL as described in the configuration section. Remember to provide a valid QUERY_API_KEY from thequery.dev for all operations.