supabase-mcp-server: a community MCP server for driving Supabase from an editor

What Query MCP exposes to a chat client

The project presents itself as an open-source MCP server that lets an IDE safely run SQL, manage schema changes, call the Supabase Management API and use the Auth Admin SDK, all with built-in safety controls. The audience is narrow and specific: developers who already have a Supabase project and want to inspect it, read its logs, alter its schema and run queries from inside Cursor, Windsurf or Cline rather than switching to a terminal and a browser dashboard.

The transport is stdio, so the server runs as a local process that an MCP client spawns and talks to. The README lists Cursor, Windsurf and Cline as compatible clients, and the distribution channel is a Python package on PyPI named supabase-mcp-server. The README also states that the package passed 17k installs on PyPI and close to 30k downloads on Smithery.ai, which is a usage count rather than a quality measure.

Packaging is deliberately modern. pyproject.toml requires Python 3.12 or newer, builds with hatchling and hatch-vcs, and ships two console entry points: supabase-mcp-server, which starts the server, and supabase-mcp-inspector, which opens the MCP inspector against it. Dependencies are narrow and purposeful: asyncpg for the database, mcp for the protocol, pglast for SQL parsing, the supabase Python SDK for management and auth calls, tenacity for retries, pyyaml for configuration and logfire for system metrics.

How a SQL statement is graded before it runs

The interesting design work is in the safety layer, not the protocol plumbing. The README describes a three-tier safety system that classifies operations as safe, write or destructive, plus runtime SQL query validation with risk level assessment. Alongside that sits a switch between read-only and read-write execution modes, so an operator can point a chat client at a production project and still keep the blast radius of a mis-generated DELETE to zero.

Two implementation details explain how that validation is done without a database round trip. The package depends on pglast, a Python binding to the real PostgreSQL parser, which means statements can be parsed with the same grammar the server would eventually hand to Postgres. And asyncpg drives the database connection, which is why the README notes that a local PostgreSQL installation is no longer required for the server itself, since asyncpg does not depend on the PostgreSQL client development libraries.

Connection handling differs between environments. Local development connects directly to 127.0.0.1:54322, the port a local Supabase stack exposes. Remote projects go through the transaction pooler rather than a direct connection, and the README says transactions are handled for both direct and pooled connections. That distinction matters because the transaction pooler hands out short-lived backend connections, so session-level state such as temporary tables or SET commands does not survive the way it would on a direct session.

Installing the server with pipx or uv

The install path is a single command for most people. The README recommends pipx because it creates an isolated environment per package, which keeps the server's dependencies out of your system Python. uv works just as well if that is your tool of choice:

# if pipx is installed (recommended)
pipx install supabase-mcp-server

# if uv is installed
uv pip install supabase-mcp-server

For local development, the README shows an editable install from a clone of the repository. The virtual environment is created with uv, then activated with the command that matches your shell:

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

After either route, the entry point supabase-mcp-server is on your PATH. Running it starts the MCP process; the companion command supabase-mcp-inspector attaches the MCP inspector so you can list the exposed tools and call them by hand before letting a model do it. The README also documents installation through Smithery.ai for users who would rather register the server with a hosted client directory.

Environment variables for a local stack and a hosted project

Configuration is entirely through environment variables, and the repository ships a .env.example you can copy to .env. The required set is short: a project reference, a database password, a region and, since version 0.4, an API key. The optional variables open up the Management API and the Auth Admin SDK.

QUERY_API_KEY=your-api-key # thequery.dev API key
SUPABASE_PROJECT_REF=your-project-ref # Your project reference from dashboard URL
SUPABASE_DB_PASSWORD=your-db-password # Database password for your project
SUPABASE_REGION=us-east-1 # Region where your Supabase project is hosted

The defaults are tuned for local work: SUPABASE_PROJECT_REF falls back to 127.0.0.1:54322 and SUPABASE_DB_PASSWORD to postgres, so a local Supabase stack connects with no configuration at all. A hosted project needs a real reference and password, and the README is emphatic about the region. Remote connections take a specific form:

postgresql://postgres.[project_ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

The region mismatch produces a specific error: the README says a 'Tenant or user not found' message is almost always a wrong SUPABASE_REGION rather than bad credentials, and points to Project Settings in the dashboard for the correct value. Getting this wrong is the most likely first-run failure, because the pooler host name embeds the region and the password alone will not fix it.

The thequery.dev key and what it changes about access

Since version 0.4 the server requires QUERY_API_KEY, a key obtained from thequery.dev, and the README states it is required for all operations. The .env.example lists the same variable with a placeholder value, and it also exposes QUERY_API_URL so that developers can point the server at a local instance of that API while working on the server itself.

This is the single most consequential fact for anyone considering adoption, and it is worth being blunt about it. The connection string, password and project reference in your environment are not the only credentials in play any more; a third-party service now sits between your client and your database toolchain. The key is mandatory even for read-only work, because the README describes it as required for all operations rather than only for the paid or networked ones. Anyone evaluating this for a regulated or air-gapped environment has to account for that dependency before anything else.

Two other configuration details are worth noting. The optional SUPABASE_ACCESS_TOKEN is what unlocks the Management API tools, since it is a personal access token rather than a database credential. The optional SUPABASE_SERVICE_ROLE_KEY is what the Auth Admin SDK calls need, and it carries far more authority than a normal client key because it bypasses row level security. Neither is required to start the server, so a minimal setup can be limited to query access against one project.

Schema versioning, management API tools and log retrieval

Beyond raw SQL, the server exposes three additional surfaces. The first is automatic versioning of database schema changes, so a migration applied through the tool is recorded rather than left as an undocumented manual edit; the repository ships a CHANGELOG.MD and a CONTRIBUTING.MD, and the package metadata points its changelog URL at the tracked CHANGELOG.MD file.

The second is the Supabase Management API, reached through the supabase Python SDK listed in the dependencies, which covers project-level operations rather than SQL. The third is the Auth Admin SDK, which lets a client create, list and modify users. The release history shows the surface growing: version 0.3.12, published on 2025-03-12, is titled 'Logs & Analytics: Log retrieval tool', and v0.4 followed on 2025-04-03.

The package metadata describes itself as a 'Community Supabase MCP server that enables Cursor and Windsurf to end-to-end manage your Supabase project, execute SQL queries, and more', and classifies its development status as 'Development Status :: 4 - Beta'. That beta label is the README's own wording about where the project stands, and it sits alongside the tool names the project claims to help Cursor and Windsurf use MCP more effectively.

Where the official Supabase MCP server takes over

The README names its own successor. It states that since Supabase released an official MCP server at supabase-community/supabase-mcp, the author has decided to no longer actively maintain this one, and recommends the official project on the grounds that it is as feature-rich and that more features will be added to it later.

The difference in approach is one of ownership rather than mechanics. Both servers speak MCP over stdio to the same category of client and both need Supabase credentials in the environment. Query MCP is a third-party Python package whose schema versioning, statement risk grading and thequery.dev key are its own design choices; the official server is shipped by the vendor whose platform it administers and can therefore evolve alongside the Management API rather than trailing it.

That matters for two audiences in particular. Teams that want the official project avoid the thequery.dev key entirely and inherit Supabase's own release cadence. Teams that want statement-level risk grading and the read-only switch still have reasons to look at this package, but they should weigh them against a server whose author has stepped back. The README's advice is the author's own, and it is the most reliable signal available for where new work will land.

Maintenance state, packaging and licence terms

The repository is not archived, and the last push was on 2026-08-21. That date records the most recent commit, not an ongoing commitment: the README explicitly says active maintenance has stopped in favour of the official server, so the project should be treated as receiving no further features even though the repository still receives commits.

Licensing is straightforward. The package is released under Apache-2.0, the pyproject.toml license field and the classifier both say so, and the repository root contains a LICENSE file. Apache-2.0 permits commercial use and modification with attribution and preservation of the licence and notices; that is a description of the terms, not legal advice, and organizations with their own review process should check the file in the repository directly. The Docker packaging follows the same shape as the Python install, building from python:3.12-slim-bookworm, installing pipx, installing the published package and running supabase-mcp-server as the container command, so a container image and a local install end up with identical behaviour.

Editorial conclusion

Adopt supabase-mcp-server if you already run Supabase, want an assistant to touch a real project, and are comfortable with a server whose author has stopped maintaining it and which now needs a key from thequery.dev. Skip it for production write access if you need a maintained upstream: the README itself points at supabase-community/supabase-mcp. Before wiring it into a client, verify that thequery.dev still issues a key for your account, that SUPABASE_REGION matches the region shown in your Project Settings, and that your pooler credentials carry the right privileges.

Frequently asked questions

Official sources

1. alexander-zuev/supabase-mcp-server on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases