supabase-mcp-server

Query MCP is an open-source Model Context Protocol (MCP) server designed to allow IDEs (like Cursor, Windsurf, and Cline) to interact safely with Supabase. It provides tools to run SQL queries, manage database schema changes, interact with the Supabase Management API, and manage users via the Supabase Auth Admin SDK.

Note: This project is no longer actively maintained. The author recommends using the official Supabase MCP server instead.

You can perform administrative tasks on remote Supabase instances using the Management API tools. Note that these tools are not compatible with local Supabase development setups.

Safety is managed via risk levels:

• safe: Read-only (GET) - always allowed.
• unsafe: State-changing (POST, PUT, PATCH, DELETE) - requires unsafe mode.
• blocked: Destructive operations (e.g., deleting a project) - never allowed.

Use live_dangerously to toggle modes.

Available Management API Tools:
- `send_management_api_request`: Sends arbitrary requests (auto-injects project ref)
- `get_management_api_spec`: Gets enriched API specification (supports filtering by domain or path)
- `get_management_api_safety_rules`: Gets all safety rules with explanations
- `live_dangerously`: Toggles between safe and unsafe operation modes

The server uses a standardized safety manager across all services (Database, API, and SDK). Operations are categorized into four risk levels, and controls are applied as follows:

1. Low Risk (e.g., SELECT, GET): Always allowed.
2. Medium Risk (e.g., INSERT, UPDATE, DELETE, POST): Requires unsafe mode to be enabled.
3. High Risk (e.g., DROP, TRUNCATE, DELETE endpoints): Requires unsafe mode AND explicit 2-step confirmation.
4. Extreme Risk (e.g., deleting projects): Always blocked.

In Windsurf, go to Cascade -> Click the hammer icon -> Configure and add the following JSON configuration. Ensure you update the command path and provide your environment variables.

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/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"
        }
      }
    }
}

You can install the supabase-mcp-server using pipx (recommended for isolated environments) or uv.

If you are developing locally, you can also install it from source using uv.

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

# Using uv
uv pip install supabase-mcp-server

In Cline (VS Code), go to the MCP Servers tab in the sidebar, click Configure MCP Servers, and edit cline_mcp_settings.json with the following configuration. You must use the full absolute path to the executable.

{
  "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"
      }
    }
  }
}

In Cursor, go to Settings -> Features -> MCP Servers and add a new server:

• Name: supabase (or any name)
• Type: command
• Command: Use the full path to the executable if the simple command fails. Use which supabase-mcp-server (macOS/Linux) or where supabase-mcp-server (Windows) to find it.

# Example command if installed via pipx
supabase-mcp-server

# Example using full path (recommended)
/full/path/to/supabase-mcp-server

If you installed via pipx or uv, local .env files in your project directory are not detected. You must use environment variables or a global config file located at:

• macOS/Linux: ~/.config/supabase-mcp/.env
• Windows: %APPDATA%\supabase-mcp\.env

To create the directory and file:

# On macOS/Linux
mkdir -p ~/.config/supabase-mcp
nano ~/.config/supabase-mcp/.env

# On Windows (PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp"
notepad "$env:APPDATA\supabase-mcp\.env"

To install for local development, clone the repository and use the following commands to set up a virtual environment and install in editable mode:

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

Claude Desktop requires the full absolute path to the executable. Using just the command name will result in a spawn ENOENT error.

1. Find the path: which supabase-mcp-server (macOS/Linux) or where supabase-mcp-server (Windows).
2. Open Claude Desktop -> Settings -> Developer -> Edit Config MCP Servers.
3. Add the following JSON:

{
  "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"
      }
    }
  }
}