MCP HubMCP Hub
alexander-zuev

supabase-mcp-server

by: alexander-zuev

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.

643created 15/02/2025
Visit
Supabase
chat

📌Overview

Purpose: The framework aims to enhance database management and interaction with Supabase by providing a secure environment for executing SQL queries and managing user authentication.

Overview: The Supabase MCP Server, evolving into Query MCP, is designed for seamless integration with various IDEs for safe execution of SQL queries while controlling user access and project management effectively. It emphasizes built-in safety controls to mitigate risks during database operations.

Key Features:

  • Safety Controls: Implements a three-tier safety system for SQL operations, ensuring only authorized actions are performed, categorized into safe, write, and destructive operations.

  • Management API Access: Provides secure integration with the Supabase Management API, allowing for comprehensive project management and user authentication tasks using Python SDK methods.

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!

Query MCP is an open-source MCP server that lets your IDE safely run SQL, manage schema changes, call the Supabase Management API, and use Auth Admin SDK — all with built-in safety controls.

Table of contents

Getting started • Feature overview • Troubleshooting • Changelog

✨ 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
  • Easy install & setup via package manager (uv, pipx, etc.)

Getting Started

Prerequisites

  • Python 3.12+

For uv installation, ensure it's installed.

PostgreSQL Installation

PostgreSQL installation is no longer required for the MCP server itself, which now uses asyncpg. However, if running a local Supabase instance:

MacOS

brew install postgresql@16

Windows

Step 1. Installation

Install the server via your preferred Python package manager:

# pipx (recommended)
pipx install supabase-mcp-server

# uv
uv pip install supabase-mcp-server

Manual install from source:

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

Step 2. Configuration

The server requires configuration to connect to your Supabase database, access the Management API, and use the Auth Admin SDK.

🔑 Important: Since v0.4 MCP server requires an API key from thequery.dev for all operations.

Environment Variables

VariableRequiredDefaultDescription
SUPABASE_PROJECT_REFYes127.0.0.1:54322Supabase project reference ID or local host:port
SUPABASE_DB_PASSWORDYespostgresDatabase password
SUPABASE_REGIONYes*us-east-1AWS region hosting your Supabase project
SUPABASE_ACCESS_TOKENNoNonePersonal access token for Management API
SUPABASE_SERVICE_ROLE_KEYNoNoneService role key for Auth Admin SDK
QUERY_API_KEYYesNoneAPI key from thequery.dev

Note: Default values are for local development; remote projects require your own values.

Connection Types

  • Database: Connects via transaction pooler endpoint. Local uses direct connection; remote uses a specific URL format. Session pooling is not supported.
  • Management API: Requires SUPABASE_ACCESS_TOKEN, works with remote Supabase only.
  • Auth Admin SDK: Requires SUPABASE_SERVICE_ROLE_KEY, connects differently for local vs. remote projects.

Configuration Methods Priority

  1. Environment Variables
  2. Local .env file (only when running from source)
  3. Global config file (~/.config/supabase-mcp/.env on macOS/Linux, %APPDATA%\supabase-mcp\.env on Windows)
  4. Default local settings

⚠️ When installed via pipx or uv, local .env files are not detected; use environment variables or global config instead.

Setting Up Configuration

  • Client-Specific Configuration (Recommended): Set env variables in your MCP client.
  • Global Configuration: Create and edit .env in the global config directory.
  • Project-Specific Configuration: (Source install only) Create .env in your project directory.

Supabase Project Info

  • Project Reference: From Supabase project URL
  • DB Password: From project settings
  • Access Token: From Supabase dashboard account tokens
  • Service Role Key: From project API keys

Supported Regions

List of supported Supabase regions (e.g., us-east-1 default).

Limitations

  • Only supports official Supabase.com and local development
  • No custom connection strings
  • No session pooling
  • API and SDK features only work with remote projects

Step 3. Usage

Compatible MCP clients supporting stdio protocol include Cursor, Windsurf, Cline, and Claude Desktop.

Cursor

Settings → Features → MCP Servers: Add new with:

name: supabase
type: command
command: supabase-mcp-server  # or full path if needed

Windsurf

Configure JSON with the command path and environment variables:

{
    "mcpServers": {
      "supabase": {
        "command": "/full/path/to/supabase-mcp-server",
        "env": {
          "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"
        }
      }
    }
}

Claude Desktop

Requires full absolute path to executable; add JSON configuration in Settings → Developer → Edit Config MCP Servers:

{
  "mcpServers": {
    "supabase": {
      "command": "/full/path/to/supabase-mcp-server",
      "env": {
        "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"
      }
    }
  }
}

Cline

Similar to Claude Desktop; configure in Cline's MCP Servers settings with full executable path and environment variables.

Troubleshooting

  • Run supabase-mcp-server from terminal to verify installation.
  • Use full path to executable in client configuration to avoid "No tools found" errors.
  • Ensure environment variables are properly set in config files or MCP client config.
  • Logs are available at:
    • macOS/Linux: ~/.local/share/supabase-mcp/mcp_server.log
    • Windows: %USERPROFILE%\.local\share\supabase-mcp\mcp_server.log
  • To view logs:
# macOS/Linux
cat ~/.local/share/supabase-mcp/mcp_server.log

# Windows PowerShell
Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"
  • For debugging, run supabase-mcp-inspector if installed from source.

Feature Overview

Database Query Tools

  • Execute PostgreSQL queries with three-tier safety system (safe, write, destructive)
  • SQL parsing and validation with PostgreSQL's parser
  • Automatic migration versioning
  • Safety controls with transaction handling and 2-step confirmation for high-risk operations
  • Tools available: listing schemas and tables, executing SQL, confirming destructive operations, retrieving migrations, toggling safety modes

Management API Tools

  • Access Supabase Management API securely with safety controls
  • Tools include sending requests, retrieving API specs and safety rules, safety mode toggling
  • Consistent risk management with operation categories (safe, unsafe, blocked)
  • Only works for remote Supabase projects

Auth Admin Tools

  • Access to Supabase Auth Admin Python SDK methods for user management
  • Tools: get_auth_admin_methods_spec, call_auth_admin_method
  • Supported user management operations: get, list, create, delete users; invite users; generate magic links; update users
  • Advantages: functionality beyond raw SQL, accuracy, simplicity, structured responses
  • Some SDK limitations noted (e.g., UUID validation, email configuration)

Logs & Analytics

  • Access Supabase logs and analytics via retrieve_logs tool
  • Log collections include: postgres, api_gateway, auth, postgrest, pooler, storage, realtime, edge_functions, cron, pgbouncer
  • Supports filters and custom SQL queries for troubleshooting

Automatic Versioning of Database Changes

  • Automatic migration script creation for write & destructive SQL operations
  • Safety modes categorized for different query types with confirmation for destructive changes

Universal Safety Mode

  • Unified safety mode across database, API, and SDK interactions
  • Risk levels: Low (always allowed), Medium (unsafe mode), High (unsafe + confirmation), Extreme (blocked)
  • Explicit confirmation required for high-risk operations

Changelog

  • Simplified installation via package manager (v0.2.0)
  • Support for different Supabase regions (v0.2.2)
  • Programmatic access to Supabase management API (v0.3.0)
  • Read and read-write SQL queries with safety controls (v0.3.0)
  • Robust transaction handling (v0.3.2)
  • Support for Python SDK methods (v0.3.6)
  • Stronger SQL query validation (v0.3.8)
  • Automatic versioning of database changes (v0.3.8)
  • Improved API spec knowledge/tools (v0.3.8)
  • Improved consistency of migration tools (v0.3.10)
  • Official release of Query MCP (v0.4.0)

For a detailed roadmap, see the discussion on GitHub.

Enjoy! ☺️