Query MCP for Supabase for Windsurf: Setup & Config

What you can do with Query MCP for Supabase in Windsurf

Supabase SQL and administration in one stdio server, with explicit query-risk controls.

• Version database schema changes during development.
• Manage users through Supabase Auth Admin methods.

Before you start: Query MCP for Supabase in Windsurf

• Python 3.12+
• uv for this launch command
• Install the supabase-mcp-server package
• A Supabase hosted project or local development instance

The README installs the package with uv pip install supabase-mcp-server before launching it. Packaged installs do not load project-local .env files. Claude Desktop requires an absolute executable path. Active maintenance has ended.

Query MCP for Supabase Windsurf configuration

1. Choose Windsurf configuration scope

   For Query MCP for Supabase, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Query MCP for Supabase to Windsurf

   Use the supabase-mcp-server entry below in mcpServers. Keep Query MCP for Supabase's documented stdio connection fields and your other Windsurf entries.

3. Check Query MCP for Supabase in Windsurf

   Query MCP for Supabase: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "supabase-mcp-server": {
      "command": "uv",
      "args": [
        "run",
        "supabase-mcp-server"
      ],
      "env": {
        "QUERY_API_KEY": "<API key from thequery.dev>",
        "SUPABASE_PROJECT_REF": "<Project reference or local host and port>",
        "SUPABASE_DB_PASSWORD": "<Database password>",
        "SUPABASE_REGION": "<Hosting region for a remote project>",
        "SUPABASE_ACCESS_TOKEN": "<Optional Management API access token>",
        "SUPABASE_SERVICE_ROLE_KEY": "<Optional Auth Admin service-role key>"
      }
    }
  }
}

Troubleshooting Query MCP for Supabase in Windsurf

• Check uv on the machine running Windsurf's MCP integration for Query MCP for Supabase; refresh MCP and inspect Cascade's tools.
• Check QUERY_API_KEY, SUPABASE_ACCESS_TOKEN, SUPABASE_DB_PASSWORD, SUPABASE_PROJECT_REF, SUPABASE_REGION, SUPABASE_SERVICE_ROLE_KEY for Query MCP for Supabase; do not bypass a Windsurf permission error with a broad administrator token.
• Query MCP for Supabase uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: No longer actively maintained by its author.
• Known limitation: Requires a separate Query API key.
• Known limitation: Does not support arbitrary connection strings or session pooling.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions