Supabase Mcp Server

What is Supabase MCP Server?

Supabase MCP Server is an MCP server that enables your favorite IDE to safely execute SQL queries, manage your database end-to-end, access the Supabase Management API, and handle user authentication—all with built-in safety controls. It is designed for developers using Cursor, Windsurf, Cline, or any MCP client that supports the stdio protocol.

How to use Supabase MCP Server?

Install the server via pipx install supabase-mcp-server or uv pip install supabase-mcp-server, then configure it with environment variables or a global .env file. The server requires a Supabase project reference, database password, and optionally an access token and service role key for Management API and Auth Admin features.

Key features of Supabase MCP Server

• Compatible with Cursor, Windsurf, Cline, and other MCP clients
• Read-only and read-write SQL execution modes
• Runtime SQL query validation with risk level assessment
• Three-tier safety system: safe, write, and destructive
• Robust transaction handling for direct and pooled connections
• Automatic versioning of database schema changes

Use cases of Supabase MCP Server

• Execute SQL queries against a Supabase database from your IDE
• Manage Supabase projects via the Management API
• Handle user authentication with the Auth Admin SDK
• Safely alter database schemas with built-in safety controls
• Manage database schema changes with automatic versioning

FAQ from Supabase MCP Server

What are the runtime dependencies?

Python 3.12 or later is required. PostgreSQL libraries are no longer needed because the server uses asyncpg. For local Supabase instances, PostgreSQL 16+ must be installed separately.

How does the server connect to the database?

It connects to your Supabase PostgreSQL database using the transaction pooler endpoint. For remote projects, the connection string is built from the project reference, password, and region. Session pooling is not supported; only transaction pooling is used.

Where does configuration data live?

Configuration is read from environment variables, a local .env file (when running from source), or a global config file at ~/.config/supabase-mcp/.env on macOS/Linux or %APPDATA%\supabase-mcp\.env on Windows.

What are the known limitations?

The server does not support self-hosted Supabase instances, custom connection strings, or session pooling. Management API and Auth Admin features only work with remote Supabase projects, not local development.

How does authentication work?

The server uses environment variables for authentication. SUPABASE_DB_PASSWORD is required for database access. SUPABASE_ACCESS_TOKEN enables the Management API, and SUPABASE_SERVICE_ROLE_KEY enables the Auth Admin SDK. All connections are made over stdio transport.