Query MCP for Supabase for Claude Code: Setup & Config

What you can do with Query MCP for Supabase in Claude Code

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

• Run SQL from an MCP-enabled IDE.
• Manage users through Supabase Auth Admin methods.

Before you start: Query MCP for Supabase in Claude Code

• 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 Claude Code configuration

1. Choose Claude Code configuration scope

   For Query MCP for Supabase, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add Query MCP for Supabase to Claude Code

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

3. Check Query MCP for Supabase in Claude Code

   Query MCP for Supabase: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "supabase-mcp-server": {
      "type": "stdio",
      "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>"
      }
    }
  }
}

claude mcp add-json --scope project 'supabase-mcp-server' '{"type":"stdio","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 Claude Code

• If Query MCP for Supabase fails to start, check uv, the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• Query MCP for Supabase: check QUERY_API_KEY, SUPABASE_ACCESS_TOKEN, SUPABASE_DB_PASSWORD, SUPABASE_PROJECT_REF, SUPABASE_REGION, SUPABASE_SERVICE_ROLE_KEY; keep credentials out of shared .mcp.json.
• Query MCP for Supabase uses stdio here: Claude Code 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 Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions