# supabase-mcp-server

> MCP Server

Query MCP enables IDEs to safely execute SQL queries, manage databases end-to-end, access Management API, and handle user authentication with built-in safety controls. Query MCP enables IDEs to safely execute

## Overview

- **Category:** Developer Tools
- **Language:** Python
- **Stars:** 830
- **Forks:** 59
- **Owner:** alexander-zuev
- **GitHub:** https://github.com/alexander-zuev/supabase-mcp-server
- **Homepage:** https://thequery.dev
- **Created:** 2025-02-15T08:54:29+00:00
- **Updated:** 2025-03-28T14:38:34+00:00
- **Source:** https://model-context-protocol.com/servers/supabase-query-management-chat-interface

## Setup

## Setup

### Prerequisites
Installing the server requires Python 3.12+.
If installing 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**
```bash
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
Install the server via `pipx install supabase-mcp-server` or `uv pip install supabase-mcp-server`.
You can also install 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:
```bash
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](https://smithery.ai/server/@alexander-zuev/supabase-mcp-server).

### 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.

#### Environment Variables
The server uses the following environment variables:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SUPABASE_PROJECT_REF` | Yes | `127.0.0.1:54322` | Your Supabase project reference ID (or local host:port) |
| `SUPABASE_DB_PASSWORD` | Yes | `postgres` | Your database password |
| `SUPABASE_REGION` | Yes* | `us-east-1` | AWS region where your Supabase project is hosted |
| `SUPABASE_ACCESS_TOKEN` | No | None | Personal access token for Supabase Management API |
| `SUPABASE_SERVICE_ROLE_KEY` | No | None | Service role key for Auth Admin SDK |

#### 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`
4. **Default Settings**: Local development defaults (if no other config is found)

#### Setting Up Configuration

##### Option 1: Client-Specific Configuration (Recommended)
Set environment variables directly in your MCP client configuration.

##### Option 2: Global Configuration
Create a global `.env` configuration file that will be used for all MCP server instances:

```bash
# 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:

```
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.

### Step 3. Usage
In general, any MCP client that supports `stdio` protocol should work with this MCP server.
Follow the guides below to install this MCP server in your client.

#### Cursor
Go to Settings -> Features -> MCP Servers and add a new server with the specified configuration.

#### Windsurf
Go to Cascade -> Click on the hammer icon -> Configure -> Fill in the configuration with the provided JSON.

#### Claude Desktop
Configure the MCP server in Claude Desktop by adding a new configuration with the provided JSON, ensuring the full path to the executable is correct.

#### Cline
Configure the MCP server in Cline by adding the provided JSON configuration to the `cline_mcp_settings.json` file.

## Tools

## Available Tools

1.  Compatible with Cursor, Windsurf, Cline and other MCP clients supporting `stdio` protocol (allows integration with various IDEs).
2.  Control read-only and read-write modes of SQL query execution (manages SQL query permissions).
3.  Runtime SQL query validation with risk level assessment (assesses the safety of SQL queries).
4.  Three-tier safety system for SQL operations: safe, write, and destructive (provides different levels of safety for SQL operations).
5.  Robust transaction handling for both direct and pooled database connections (ensures data consistency).
6.  Automatic versioning of database schema changes (tracks database schema modifications).
7.  Manage your Supabase projects with Supabase Management API (allows managing Supabase projects).
8.  Manage users with Supabase Auth Admin methods via Python SDK (enables user management).
9.  Pre-built tools to help Cursor & Windsurf work with MCP more effectively (improves integration with specific IDEs).
10. Dead-simple install & setup via package manager (uv, pipx, etc.) (simplifies installation).
11. `get_schemas` (Lists schemas with sizes and table counts).
12. `get_tables` (Lists tables, foreign tables, and views with metadata).
13. `get_table_schema` (Gets detailed table structure (columns, keys, relationships)).
14. `execute_postgresql` (Executes SQL statements against your database).
15. `confirm_destructive_operation` (Executes high-risk operations after confirmation).
16. `retrieve_migrations` (Gets migrations with filtering and pagination options).
17. `live_dangerously` (Toggles between safe and unsafe modes).
18. `send_management_api_request` (Sends arbitrary requests to Supabase Management API with auto-injection of project ref).
19. `get_management_api_spec` (Gets the enriched API specification with safety information).
20. `get_management_api_safety_rules` (Gets all safety rules with human-readable explanations).
21. `get_auth_admin_methods_spec` (retrieves documentation for all available Auth Admin methods).
22. `call_auth_admin_method` (directly invoke Auth Admin methods with proper parameter handling).
23. `retrieve_logs` (Access logs from any Supabase service).