home / mcp / supabase mcp server
Supabase MCP Server enabling Cursor & Windsurf to use any method from Management API and query your database
Configuration
View docs{
"mcpServers": {
"deploya-labs-mcp-supabase": {
"command": "supabase-mcp-server",
"args": [],
"env": {
"SUPABASE_REGION": "us-east-1",
"SUPABASE_DB_PASSWORD": "your-db-password",
"SUPABASE_PROJECT_REF": "project-ref",
"SUPABASE_ACCESS_TOKEN": "your-access-token"
}
}
}
}This MCP Server lets Cursor and Windsurf safely interact with Supabase databases, enabling you to run SQL queries, manage Supabase projects via the Management API, and work with Auth Admin methods in a controlled, writable/read-only mode when needed. It provides safeguards and easy install paths so you can integrate Supabase into your MCP workflow with confidence.
Connect your MCP clients (Cursor or Windsurf) to the Supabase MCP Server to execute queries, manage schemas, and access Supabase APIs. Start in read-only mode by default and switch to read-write only when you explicitly enable it. Expect safe, transactional behavior for both direct database connections and transaction-pooled connections. Use the provided environment variables to point the server at your Supabase project and database.
Practical usage patterns include running read-only SELECT queries to fetch data, using explicit transactions for write operations, and performing DDL changes only with explicit BEGIN/COMMIT blocks when you’re operating over pooled connections. You can also leverage management API tools to interact with your Supabase project and Auth Admin methods to manage users, all through the MCP server interface.
Prerequisites you need before installation are: Python 3.12 or newer and PostgreSQL 16 or newer. If you plan to install via the uv runtime, ensure uv is installed as well.
Install the MCP server with one of the supported package managers. The recommended method uses isolated environments.
# if pipx is installed (recommended)
pipx install supabase-mcp-server
# if uv is installed
uv pip install supabase-mcp-server
```
# Optional: install from source for local development
uv venv
# On Mac
source .venv/bin/activate
# On Windows
.venv\Scripts\activate
uv pip install -e .Configuration is done via environment variables for remote Supabase projects or local defaults for a local Supabase instance. The server supports both local and remote connections, and you can tailor connection settings for Cursor or Windsurf depending on your workflow.
For local development, the server is pre-configured to connect to a local instance with default settings: Host 127.0.0.1:54322 and Password postgres. If you do not modify these settings, you do not need to set environment variables for local use.
For remote Supabase projects, configure the following environment variables (either in a global config file or per-project environment area): SUPABASE_PROJECT_REF, SUPABASE_DB_PASSWORD, SUPABASE_REGION (optional), and SUPABASE_ACCESS_TOKEN (optional). These values drive the remote connection and API access.
Cursor configuration can be done per-project or globally. For per-project MCP setup, create a mcp.json in your project and include a configuration that points to the server command. For global configuration, place an environment file at a global config path and ensure the variables are set there.
Windsurf uses a JSON configuration file mcp_config.json to specify the server command and environment variables, with the same SUPABASE_* variables to establish the remote connection.
Key tools exposed by the MCP server include database query tools (get_db_schemas, get_tables, get_table_schema, execute_sql_query), management API tools (send_management_api_request, get_management_api_spec, get_management_api_safety_rules, live_dangerously), and Auth Admin tools (get_auth_admin_methods_spec, call_auth_admin_method). These tools enable a wide range of read and write operations with built-in safety controls.
Troubleshooting tips: verify the MCP server runs directly by calling the command in a terminal, ensure the correct path to the server executable is provided in your client configuration, and check the global or local .env files for the right SUPABASE_* values. Server logs are available at the designated user data locations to help diagnose connection status and operation results.
The server starts in read-only mode by default and only enables write operations after you explicitly switch modes. It automatically returns to read-only after a write operation to reduce accidental data changes. Some advanced transaction patterns may be affected when using certain remote connection modes, so prefer explicit transactions (BEGIN/COMMIT) for DDL changes in pooled environments.
Safety for the Supabase Management API is provided by categorizing methods into safe, unsafe, and blocked. You can toggle between safe and unsafe modes, but certain destructive operations (like deleting a project or a database) remain blocked regardless of the mode.
Lists all database schemas with their sizes and table counts.
Lists all tables in a schema with sizes, row counts, and metadata.
Gets detailed table structure including columns, keys, and relationships.
Executes raw SQL queries with support for all PostgreSQL operations and transaction control.
Switch between safe and unsafe modes for Management API access.
Send arbitrary requests to Supabase Management API with auto-injection of project ref and safety controls.
Retrieve the enriched API specification with safety information.
Retrieve all safety rules including blocked and unsafe operations.
Retrieve documentation for available Auth Admin methods.
Invoke Auth Admin methods with proper parameter handling.