How to add Query | Supabase MCP Server to Windsurf

Safely run SQL, manage schema, call the Supabase Management API & Auth Admin from your IDE — with built-in safety controls. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 826★ · stdio · apikey

Windsurf config for Query | Supabase MCP Server

pipx install supabase-mcp-server

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

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Query | Supabase MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Query | Supabase MCP Server's tools become available to Cascade.

Before you start

Python 3.12+
uv (if installing via uv) or pipx (recommended)
PostgreSQL 16+ only if running a local Supabase instance
A free QUERY_API_KEY from thequery.dev (required for all operations since v0.4)
Supabase project reference and database password (for remote projects)
SUPABASE_ACCESS_TOKEN for Management API tools (optional, remote only)
SUPABASE_SERVICE_ROLE_KEY for Auth Admin tools (optional)

What Query | Supabase MCP Server can do in Windsurf

get_schemas

Lists database schemas with their sizes and table counts.

get_tables

Lists tables, foreign tables, and views with metadata for a given schema.

get_table_schema

Gets detailed table structure including columns, keys, and relationships.

execute_postgresql

Executes SQL statements against your Supabase database, with risk assessment and safety controls.

confirm_destructive_operation

Executes high-risk (destructive) operations after explicit 2-step confirmation.

retrieve_migrations

Gets database migrations with filtering and pagination options.

live_dangerously

Toggles between safe (read-only) and unsafe operation modes for database and API operations.

send_management_api_request

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

Security

Requires a free QUERY_API_KEY from thequery.dev for all operations (since v0.4). Defaults to a SAFE read-only mode; write operations require enabling unsafe mode via the live_dangerously tool, and destructive operations additionally require explicit 2-step confirmation. Extreme-risk operations (e.g. deleting a project) are blocked entirely. SUPABASE_SERVICE_ROLE_KEY (for Auth Admin) and SUPABASE_ACCESS_TOKEN (for the Management API) are highly privileged credentials and should be handled accordingly. Only supports official Supabase.com hosted projects and local development — no self-hosted support.

Query | Supabase MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Query | Supabase MCP Server config there under the "mcpServers" key and restart the client.

Is Query | Supabase MCP Server safe to use with Windsurf?

Is this the official Supabase MCP server?

No. This is an independent open-source server by alexander-zuev. The README notes that Supabase has since released its own official MCP server (supabase-community/supabase-mcp), and the author has decided to no longer actively maintain this one.

Do I need an API key?

Yes. Since v0.4, the server requires a QUERY_API_KEY which you can get for free at thequery.dev; it is required for all operations.

Which MCP clients are supported?

Any MCP client supporting the stdio protocol. It was explicitly tested with Cursor, Windsurf, Cline, and Claude Desktop, and can also be installed via Smithery.ai.

View repo Full Query | Supabase MCP Server page