supabase-mcp-server

Executes PostgreSQL queries against Supabase databases with automatic risk classification into three tiers: Safe (SELECT-only, always allowed), Write (INSERT/UPDATE/DELETE, requires unsafe mode), and Destructive (DROP/CREATE, requires unsafe mode + explicit confirmation). The system parses incoming SQL, classifies operations by AST analysis, and enforces execution gates based on the current safety mode setting, preventing accidental schema destruction while enabling controlled data mutations.

Automatically versions and tracks database schema changes by capturing migration metadata (timestamp, operation type, SQL statement) whenever destructive or schema-modifying operations execute. The system maintains a migration history log that can be queried to understand schema evolution, rollback points, and audit trails of who changed what when. This integrates with Supabase's native migration system to ensure version consistency across environments.

Catches and handles exceptions from database operations, Management API calls, and Auth SDK invocations, preserving error context (stack trace, operation details, input parameters) and returning user-friendly error messages. The system distinguishes between recoverable errors (connection timeouts, rate limits) and fatal errors (authentication failures, invalid SQL), and provides actionable error messages that help developers understand what went wrong. This prevents cryptic error messages from reaching users and enables better debugging.

Provides Dockerfile and Docker Compose configuration for containerizing the MCP server, enabling deployment in Docker environments with environment variable injection for credentials. The system builds a Python 3.12 container with all dependencies, exposes the stdio interface for MCP clients, and supports environment variable configuration for different deployment scenarios. This enables easy deployment to cloud platforms (AWS, GCP, Azure) and local Docker environments without manual setup.

Provides a testing framework with mock Supabase clients (database, Management API, Auth SDK) for unit testing without real Supabase credentials, and integration tests that run against a real Supabase instance. The system uses pytest for test execution, fixtures for test setup/teardown, and parametrized tests for testing multiple scenarios. This enables developers to test MCP tools locally without requiring a Supabase account and to verify integration with real Supabase services in CI/CD pipelines.

Provides MCP tool bindings for all Supabase Management API endpoints (project management, database configuration, auth settings, etc.) with automatic risk assessment and safety controls. The system maps Management API operations to MCP tools, injects project references automatically, classifies each endpoint by risk level (read-only vs destructive), and enforces safety gates similar to SQL execution. This enables chat-driven management of Supabase project infrastructure without requiring manual API calls or authentication.

Exposes Supabase Auth Admin SDK methods as MCP tools, enabling chat-driven user management operations including user creation, updates, deletion, authentication operations (magic links, password recovery), and MFA management. The system wraps Auth Admin SDK calls with proper error handling, validates input parameters, and integrates with the safety system to require confirmation for destructive user operations (deletion, password resets). This allows developers to manage authentication state and user accounts without leaving their IDE.

Provides MCP tools to query Supabase logs across multiple collections (postgres, api_gateway, auth, realtime, etc.) with filtering by time range, search text, and custom criteria. The system constructs log queries using Supabase's log API, handles pagination for large result sets, and returns structured log entries as JSON objects. This enables developers to troubleshoot issues, monitor application behavior, and analyze performance without leaving their IDE or switching to the Supabase dashboard.

Implements the Model Context Protocol (MCP) server specification using stdio transport, registering all database, management API, auth, and logging capabilities as MCP tools that can be invoked by compatible clients (Cursor, Windsurf, Cline, Claude Desktop). The system handles MCP protocol messages (tool calls, responses, errors), manages tool schemas with JSON Schema validation, and maintains bidirectional communication with MCP clients. This enables seamless integration of Supabase operations into AI-assisted development workflows without custom client code.

Loads and validates Supabase credentials and configuration from environment variables (SUPABASE_URL, SUPABASE_DB_URL, SUPABASE_SERVICE_ROLE_KEY, SUPABASE_MANAGEMENT_API_TOKEN) with type checking and required field validation. The system uses a settings container pattern to manage configuration state, validates credentials at startup, and provides clear error messages if required variables are missing or invalid. This enables secure credential management without hardcoding secrets and supports multiple deployment environments (development, staging, production).

Manages PostgreSQL connections to Supabase using asyncpg with support for both direct connections and pooled connections via PgBouncer. The system creates and maintains a connection pool, handles connection lifecycle (creation, reuse, cleanup), and provides async context managers for safe connection usage. This enables efficient concurrent query execution without exhausting database connections and supports both development (direct) and production (pooled) connection patterns.

Provides transaction management for SQL queries with automatic rollback on errors, ensuring database consistency. The system wraps queries in asyncpg transactions, catches exceptions during execution, rolls back changes if errors occur, and returns detailed error messages. This prevents partial updates and ensures that either all operations in a transaction succeed or none do, maintaining data integrity even when LLM-generated SQL contains errors.

Queries PostgreSQL system catalogs (pg_tables, pg_columns, pg_indexes, etc.) to extract database schema metadata including table names, column definitions, data types, constraints, and indexes. The system provides MCP tools to list tables, describe table structure, and retrieve index information, enabling developers to understand the database schema without manual SQL queries. This metadata is used by LLM agents to generate contextually appropriate SQL and understand what operations are possible.