home / mcp / supabase mcp server

Supabase MCP Server

Query MCP enables end-to-end management of Supabase via chat interface: read & write query executions, management API support, automatic migration versioning, access to logs and much more.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "alexander-zuev-supabase-mcp-server": {
      "command": "/Users/username/.local/bin/supabase-mcp-server",
      "args": [],
      "env": {
        "QUERY_API_KEY": "YOUR_API_KEY",
        "SUPABASE_REGION": "us-east-1",
        "SUPABASE_DB_PASSWORD": "YOUR_DB_PASSWORD",
        "SUPABASE_PROJECT_REF": "YOUR_PROJECT_REF",
        "SUPABASE_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN",
        "SUPABASE_SERVICE_ROLE_KEY": "YOUR_SERVICE_ROLE_KEY"
      }
    }
  }
}

You can run a safe, SQL-aware MCP server that lets your IDE execute PostgreSQL queries, manage schema migrations, call the Supabase Management API, and use the Auth Admin SDK, all with built-in safety controls. This server focuses on safe collaboration between your editor and a remote Supabase project, giving you controlled access to data, schema changes, and admin functionalities from your development environment.

How to use

You connect to the MCP server from supported clients that use the stdio protocol. After you configure the server in your client, you can run safe read-only queries by default and enable write or destructive operations only when you explicitly toggle unsafe mode and, for high-risk actions, confirm the operation.

How to install

Prerequisites: Make sure you have Python 3.12+ installed on your system. If you plan to run the server via a package manager, ensure the package manager is available (pipx is recommended). If you prefer using uv, have uv installed.

Install via pipx (recommended for isolated environments):

pipx install supabase-mcp-server

Install via uv (if you already have uv):

uv pip install supabase-mcp-server

Install manually from source (editable installation):

uv venv
# On Mac
source .venv/bin/activate
# On Windows
.venv\Scripts\activate
uv pip install -e .

Additional sections

Configuration, security, and usage notes help you connect securely to your Supabase project and run operations with proper safety checks.

Configuration details include environment variables for the Supabase project reference, database password, region, access token for the Management API, service role key for Auth Admin SDK, and the API key needed for all operations.

Environment variables you will typically set include: SUPABASE_PROJECT_REF, SUPABASE_DB_PASSWORD, SUPABASE_REGION, SUPABASE_ACCESS_TOKEN, SUPABASE_SERVICE_ROLE_KEY, QUERY_API_KEY. These values govern how the server connects to your database, Management API, and Auth Admin SDK.

Note on regions: specify SUPABASE_REGION for remote projects to match your Supabase hosting region. If you see a mismatch error like “Tenant or user not found,” double-check the region setting.

Usage of safety modes: the server categorizes operations as safe, write, destructive, or extreme. Read-only queries are allowed by default. Write and destructive actions require enabling unsafe mode, with destructive actions also requiring explicit confirmation.

For local development and testing, you can use a local PostgreSQL instance, but the server uses asyncpg with a transaction pooler. Remote Supabase projects are supported for Management API and Auth Admin SDK features.

Troubleshooting tips cover verifying installation by running the server binary directly, confirming the correct executable path in your client, and checking logs for connection and configuration details.

MCP Inspector is a helpful debugging tool you can run to get a complete overview of server status and configurations when installed from source.

Notes on configuration and tooling

The server exposes a set of tools to manage your Supabase project and database. You can execute SQL safely, manage schemas with automatic migration versioning, and use admin SDK features for user management and API access.

Available tools

get_schemas

List schemas with sizes and table counts in the connected database.

get_tables

List tables, foreign tables, and views with metadata.

get_table_schema

Get detailed structure of a specific table, including columns and keys.

execute_postgresql

Execute SQL statements against the connected PostgreSQL database with safety checks.

confirm_destructive_operation

Execute high-risk destructive operations after explicit confirmation.

retrieve_migrations

Fetch migration records with filtering and pagination.

live_dangerously

Toggle between safe and unsafe modes for broader operation scope.

send_management_api_request

Send requests to the Supabase Management API with automatic project_ref injection.

get_management_api_spec

Retrieve enriched API specification with safety and risk information.

get_management_api_safety_rules

Fetch safety rules for API endpoints with explanations.

live_dangerously

Toggle between safe and unsafe operation modes across services.

get_auth_admin_methods_spec

Retrieve documentation for available Auth Admin methods.

call_auth_admin_method

Invoke Auth Admin methods with proper parameter handling.

get_user_by_id

Retrieve a user by their UUID.

list_users

List users with pagination.

create_user

Create a new user in the Auth system.

delete_user

Delete a user by their ID.

invite_user_by_email

Send an invite link to a user's email.

generate_link

Generate authentication-related links (signup, magic link, recovery).

update_user_by_id

Update user attributes by ID.

delete_factor

Remove a factor from a user (not fully implemented in SDK).

retrieve_logs

Access logs from various Supabase services for debugging.