Supabase

by alexander-zuev

661 stars

604 downloads

Not rated

GitHub

About

Integrates with Supabase to enable natural language-driven database schema exploration, management, and read-only SQL query execution.

Details

Author: alexander-zuev
Repository: alexander-zuev/supabase-mcp-server
GitHub stars: 661
Downloads: 604
License: Apache License 2.0
Categories: Database, Productivity, AI, Developer Tools, Search, Knowledge Base, Infrastructure, Cloud Service
Tags: #integration

- 💻 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.)

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Supabase

Command (node, npx, python, etc.) /Users/username/.local/bin/supabase-mcp-server
Environment
- 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
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "C:\\Users\\username\\.local\\bin\\supabase-mcp-server.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "C:\\Users\\username\\.local\\bin\\supabase-mcp-server.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "C:\\Users\\username\\.local\\bin\\supabase-mcp-server.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "C:\\Users\\username\\.local\\bin\\supabase-mcp-server.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "C:\\Users\\username\\.local\\bin\\supabase-mcp-server.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

From the repository

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

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

pipx install supabase-mcp-server

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.

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

uv venv

uv pip install -e .

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

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.

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 |
| QUERY_API_KEY | Yes | None | API key from thequery.dev (required for all operations) |

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

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)

> ⚠️ 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.

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.

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

``bash

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.

In general, any MCP client that supports stdio` protocol should work with this MCP server. This server was explicitly tested to work with:
- Cursor
- Windsurf
- Cline
- Claude Desktop

Additionally, you can also use smithery.ai to install this server a number of clients, including the ones above.

Follow the guides below to install this MCP server in your client.

`get_schemas`

Lists schemas with sizes and table counts.

`get_tables`

Lists tables, foreign tables, and views with metadata.

`get_table_schema`

Gets detailed table structure (columns, keys, relationships).

`execute_postgresql`

Executes SQL statements against your database.

`confirm_destructive_operation`

Executes high-risk operations after confirmation.

`retrieve_migrations`

Gets migrations with filtering and pagination options.

`live_dangerously`

Toggles between safe and unsafe modes.

`send_management_api_request`

Sends arbitrary requests to Supabase Management API with auto-injection of project ref.

`get_management_api_spec`

Gets the enriched API specification with safety information. Supports multiple query modes.

`get_management_api_safety_rules`

Gets all safety rules with human-readable explanations.

`get_auth_admin_methods_spec`

Retrieves documentation for all available Auth Admin methods.

`call_auth_admin_method`

Directly invokes Auth Admin methods with proper parameter handling.

`get_user_by_id`

Retrieve a user by their ID.

`list_users`

List all users with pagination.

`create_user`

Create a new user.

`delete_user`

Delete a user by their ID.

`invite_user_by_email`

Send an invite link to a user's email.

`generate_link`

Generate an email link for various authentication purposes.

`update_user_by_id`

Update user attributes by ID.

`delete_factor`

Delete a factor on a user (currently not implemented in SDK).

`retrieve_logs`

Access logs from any Supabase service.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "supabase": {
            "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"
            },
            "args": [],
            "command": "/Users/username/.local/bin/supabase-mcp-server"
        }
    }
}

Linux

{
    "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"
    },
    "args": [],
    "command": "/Users/username/.local/bin/supabase-mcp-server"
}

Macos

{
    "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"
    },
    "args": [],
    "command": "/Users/username/.local/bin/supabase-mcp-server"
}

Windows

{
    "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"
    },
    "args": [],
    "command": "C:\\Users\\username\\.local\\bin\\supabase-mcp-server.exe"
}

🌅 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.** ](https://github.com/supabase-community/supabase-mcp)[Getting started•](#getting-started)[Feature overview•](#feature-overview)[Troubleshooting•](#troubleshooting)[Changelog - 💻 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.) Installing the server requires the following on your system: If you plan to install via`uv`, ensure it's](#changelog)[installed. 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: - Download and install PostgreSQL 16+ from](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_1)[https://www.postgresql.org/download/windows/ - Ensure "PostgreSQL Server" and "Command Line Tools" are selected during 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. 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 .` ``` You can find the full instructions on how to use Smithery.ai to connect to this MCP server](https://www.postgresql.org/download/windows/)[here. 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](https://smithery.ai/server/@alexander-zuev/supabase-mcp-server)[thequery.devto use this MCP server. 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. - 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.](https://thequery.dev)[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. - 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) - 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` The server looks for configuration in this order (highest to lowest priority): - **Environment Variables**: Values set directly in your environment - **Local`.env`File**: A`.env`file in your current working directory (only works when running from source) - **Global Config File**: - Windows:`%APPDATA%\supabase-mcp\.env` - macOS/Linux:`~/.config/supabase-mcp/.env` ⚠️**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. 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. 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` ``` 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 - **Service Role Key**: Found in Project Settings → API → Project API keys The server supports all Supabase regions: - `us-west-1`- West US (North California) - `us-east-1`- East US (North Virginia) - default - `us-east-2`- East US (Ohio) - `ca-central-1`- Canada (Central) - `eu-west-1`- West EU (Ireland) - `eu-west-2`- West Europe (London) - `eu-west-3`- West EU (Paris) - `eu-central-1`- Central EU (Frankfurt) - `eu-central-2`- Central Europe (Zurich) - `eu-north-1`- North EU (Stockholm) - `ap-south-1`- South Asia (Mumbai) - `ap-southeast-1`- Southeast Asia (Singapore) - `ap-northeast-1`- Northeast Asia (Tokyo) - `ap-northeast-2`- Northeast Asia (Seoul) - `ap-southeast-2`- Oceania (Sydney) - `sa-east-1`- South America (São Paulo) - **No Self-Hosted Support**: The server only supports official Supabase.com hosted projects and local development - **No Connection String Support**: Custom connection strings are not supported - **No Session Pooling**: Only transaction pooling is supported for database connections - **API and SDK Features**: Management API and Auth Admin SDK features only work with remote Supabase projects, not local development In general, any MCP client that supports`stdio`protocol should work with this MCP server. This server was explicitly tested to work with: Additionally, you can also use smithery.ai to install this server a number of clients, including the ones above. Follow the guides below to install this MCP server in your client. Go to Settings -> Features -> MCP Servers and add a new server with this configuration: ``` `# can be set to any name name: supabase type: command # if you installed with pipx command: supabase-mcp-server # if you installed with uv command: uv run supabase-mcp-server # if the above doesn't work, use the full path (recommended) command: /full/path/to/supabase-mcp-server # Find with 'which supabase-mcp-server' (macOS/Linux) or 'where supabase-mcp-server' (Windows)` ``` If configuration is correct, you should see a green dot indicator and the number of tools exposed by the server. Go to Cascade -> Click on the hammer icon -> Configure -> Fill in the configuration: ``` `{ "mcpServers": { "supabase": { "command": "/Users/username/.local/bin/supabase-mcp-server", // update path "env": { "QUERY_API_KEY": "your-api-key", // Required - get your API key at thequery.dev "SUPABASE_PROJECT_REF": "your-project-ref", "SUPABASE_DB_PASSWORD": "your-db-password", "SUPABASE_REGION": "us-east-1", // optional, defaults to us-east-1 "SUPABASE_ACCESS_TOKEN": "your-access-token", // optional, for management API "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key" // optional, for Auth Admin SDK } } } }` ``` If configuration is correct, you should see green dot indicator and clickable supabase server in the list of available servers. Claude Desktop also supports MCP servers through a JSON configuration. Follow these steps to set up the Supabase MCP server: - **Find the full path to the executable**(this step is critical): ``` `# On macOS/Linux which supabase-mcp-server # On Windows where supabase-mcp-server` ``` Copy the full path that is returned (e.g.,`/Users/username/.local/bin/supabase-mcp-server`). **Configure the MCP server**in Claude Desktop: - Open Claude Desktop - Go to Settings → Developer -> Edit Config MCP Servers - Add a new configuration with the following JSON: ``` `{ "mcpServers": { "supabase": { "command": "/full/path/to/supabase-mcp-server", // Replace with the actual path from step 1 "env": { "QUERY_API_KEY": "your-api-key", // Required - get your API key at thequery.dev "SUPABASE_PROJECT_REF": "your-project-ref", "SUPABASE_DB_PASSWORD": "your-db-password", "SUPABASE_REGION": "us-east-1", // optional, defaults to us-east-1 "SUPABASE_ACCESS_TOKEN": "your-access-token", // optional, for management API "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key" // optional, for Auth Admin SDK } } } }` ``` ⚠️**Important**: Unlike Windsurf and Cursor, Claude Desktop requires the**full absolute path**to the executable. Using just the command name (`supabase-mcp-server`) will result in a "spawn ENOENT" error. If configuration is correct, you should see the Supabase MCP server listed as available in Claude Desktop. Cline also supports MCP servers through a similar JSON configuration. Follow these steps to set up the Supabase MCP server: - **Find the full path to the executable**(this step is critical): ``` `# On macOS/Linux which supabase-mcp-server # On Windows where supabase-mcp-server` ``` Copy the full path that is returned (e.g.,`/Users/username/.local/bin/supabase-mcp-server`). - Open Cline in VS Code - Click on the "MCP Servers" tab in the Cline sidebar - Click "Configure MCP Servers" - This will open the`cline_mcp_settings.json`file - Add the following configuration: ``` `{ "mcpServers": { "supabase": { "command": "/full/path/to/supabase-mcp-server", // Replace with the actual path from step 1 "env": { "QUERY_API_KEY": "your-api-key", // Required - get your API key at thequery.dev "SUPABASE_PROJECT_REF": "your-project-ref", "SUPABASE_DB_PASSWORD": "your-db-password", "SUPABASE_REGION": "us-east-1", // optional, defaults to us-east-1 "SUPABASE_ACCESS_TOKEN": "your-access-token", // optional, for management API "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key" // optional, for Auth Admin SDK } } } }` ``` If configuration is correct, you should see a green indicator next to the Supabase MCP server in the Cline MCP Servers list, and a message confirming "supabase MCP server connected" at the bottom of the panel. Here are some tips & tricks that might help you: - **Debug installation**- run`supabase-mcp-server`directly from the terminal to see if it works. If it doesn't, there might be an issue with the installation. - **MCP Server configuration**- if the above step works, it means the server is installed and configured correctly. As long as you provided the right command, IDE should be able to connect. Make sure to provide the right path to the server executable. - **"No tools found" error**- If you see "Client closed - no tools available" in Cursor despite the package being installed: - Find the full path to the executable by running`which supabase-mcp-server`(macOS/Linux) or`where supabase-mcp-server`(Windows) - Use the full path in your MCP server configuration instead of just`supabase-mcp-server` - For example:`/Users/username/.local/bin/supabase-mcp-server`or`C:\Users\username\.local\bin\supabase-mcp-server.exe` - Log file location: - macOS/Linux:`~/.local/share/supabase-mcp/mcp_server.log` - Windows:`%USERPROFILE%\.local\share\supabase-mcp\mcp_server.log` ``` `# On macOS/Linux cat ~/.local/share/supabase-mcp/mcp_server.log # On Windows (PowerShell) Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"` ``` If you are stuck or any of the instructions above are incorrect, please raise an issue. A super useful tool to help debug MCP server issues is MCP Inspector. If you installed from source, you can run`supabase-mcp-inspector`from the project repo and it will run the inspector instance. Coupled with logs this will give you complete overview over what's happening in the server. 📝 Running`supabase-mcp-inspector`, if installed from package, doesn't work properly - I will validate and fix in the coming release. Since v0.3+ server provides comprehensive database management capabilities with built-in safety controls: - **SQL Query Execution**: Execute PostgreSQL queries with risk assessment - **Three-tier safety system**: - `safe`: Read-only operations (SELECT) - always allowed - `write`: Data modifications (INSERT, UPDATE, DELETE) - require unsafe mode - `destructive`: Schema changes (DROP, CREATE) - require unsafe mode + confirmation - Uses PostgreSQL's parser (pglast) for accurate analysis and provides clear feedback on safety requirements - Database-altering operations operations are automatically versioned - Generates descriptive names based on operation type and target - Default SAFE mode allows only read-only operations - All statements run in transaction mode via`asyncpg` - 2-step confirmation for high-risk operations - `get_schemas`: Lists schemas with sizes and table counts - `get_tables`: Lists tables, foreign tables, and views with metadata - `get_table_schema`: Gets detailed table structure (columns, keys, relationships) - `execute_postgresql`: Executes SQL statements against your database - `confirm_destructive_operation`: Executes high-risk operations after confirmation - `retrieve_migrations`: Gets migrations with filtering and pagination options - `live_dangerously`: Toggles between safe and unsafe modes Since v0.3.0 server provides secure access to the Supabase Management API with built-in safety controls:](https://supabase.com/dashboard/account/tokens)

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

get_schemas

get_tables

get_table_schema

execute_postgresql

confirm_destructive_operation

retrieve_migrations

live_dangerously

send_management_api_request

get_management_api_spec

get_management_api_safety_rules

get_auth_admin_methods_spec

call_auth_admin_method

get_user_by_id

list_users

create_user

delete_user

invite_user_by_email

generate_link

update_user_by_id

delete_factor

retrieve_logs

Claude Desktop / Cursor

Linux

Macos

Windows

Install

More like this

Redis

Time

Sqlite

PostgreSQL

Context 7

Sequential Thinking

`get_schemas`

`get_tables`

`get_table_schema`

`execute_postgresql`

`confirm_destructive_operation`

`retrieve_migrations`

`live_dangerously`

`send_management_api_request`

`get_management_api_spec`

`get_management_api_safety_rules`

`get_auth_admin_methods_spec`

`call_auth_admin_method`

`get_user_by_id`

`list_users`

`create_user`

`delete_user`

`invite_user_by_email`

`generate_link`

`update_user_by_id`

`delete_factor`

`retrieve_logs`