Supabase MCP Server

Exposes Supabase Management API and PostgREST API through the Model Context Protocol using a monorepo architecture with three distribution channels: hosted HTTP endpoint at mcp.supabase.com with OAuth 2.1 Dynamic Client Registration, npm package with three entry points (CLI binary, programmatic SDK, server factory), and local development via Supabase CLI at localhost:54321/mcp. Uses a platform abstraction layer that decouples transport mechanisms from tool implementations, enabling any MCP-compatible client (Claude Desktop, Cursor, VS Code Copilot, Windsurf) to connect without custom integrations.

Executes arbitrary SQL queries against Supabase PostgreSQL databases through a dedicated PostgREST MCP server (@supabase/mcp-server-postgrest) that translates MCP tool calls into PostgREST HTTP requests. Supports parameterized queries to prevent SQL injection, result streaming for large datasets, and automatic schema introspection. The implementation uses a query builder pattern that constructs PostgREST-compatible request payloads, handling authentication via Supabase service role keys and managing connection pooling through the PostgREST proxy layer.

Provides a comprehensive testing framework and mock system for developing and testing MCP tools without requiring live Supabase project access. The mock system includes mock implementations of Supabase APIs, tool registry mocking, and test utilities for verifying tool behavior. Enables developers to write unit tests for tools, test error handling and edge cases, and validate tool schemas without external dependencies. The testing framework integrates with standard Node.js testing tools and provides fixtures for common test scenarios.

Implements OAuth 2.1 Dynamic Client Registration protocol for authenticating MCP clients connecting to the hosted HTTP endpoint at mcp.supabase.com/mcp. The authentication flow uses Dynamic Client Registration to dynamically register MCP clients without pre-configured credentials, issuing access tokens that authorize tool access. The implementation handles token validation, scope-based access control, and token refresh for long-lived connections. Supports both interactive OAuth flows for user-facing clients and service account flows for programmatic access.

Supports three independent distribution channels (hosted HTTP endpoint, npm package, CLI via stdio) with unified tool implementations that work across all channels without modification. The platform abstraction layer handles transport-specific details (HTTP request/response, stdio message protocol, programmatic function calls) while tools implement business logic once. Each distribution channel can be deployed independently with different feature group configurations, authentication mechanisms, and operational requirements. The architecture enables users to choose the distribution channel that best fits their deployment model.

Provides a testing framework and mock API system that allows MCP server implementations to be tested without requiring live Supabase API credentials or network access. The mock system (@supabase/mcp-utils) includes predefined mock responses for common operations and allows custom mock configurations for testing edge cases. Tests can verify tool behavior, error handling, and response formatting without external dependencies.

Manages Supabase database structure (create/drop/alter tables, columns, indexes, constraints) through the Supabase Management API, translated into MCP tool calls. Implements a schema-aware tool architecture that validates DDL operations before execution, provides schema introspection for understanding current database structure, and supports migration workflows. The platform abstraction layer handles API authentication and request construction, while tool implementations encapsulate domain logic for table creation, column modifications, and constraint management.

Manages Supabase Auth users (create, list, update, delete, reset passwords) through the Supabase Management API, exposed as MCP tools. Implements account management tool group that handles user lifecycle operations, password resets, and user metadata updates. The implementation validates user input, enforces authentication policies, and integrates with Supabase's built-in auth system without requiring direct access to auth tables. Tool architecture includes safety checks to prevent unauthorized user modifications and audit logging for compliance.

Manages Supabase Storage buckets and files (create buckets, upload/download/delete files, set access policies) through MCP tools that call the Supabase Management API and Storage API. Implements storage tool group with operations for bucket lifecycle management, file operations with metadata, and access control configuration. The implementation handles file streaming for large uploads/downloads, manages authentication tokens for Storage API access, and provides bucket policy configuration for public/private access patterns.

Deploys and invokes Supabase Edge Functions (serverless TypeScript functions) through MCP tools that call the Supabase Management API. Implements edge functions tool group with operations for function deployment from code strings, function invocation with parameters, and function metadata management. The implementation handles function code compilation, manages deployment to Deno runtime, and provides request/response handling for function invocation with automatic serialization of parameters and results.

Manages Supabase database branching (create preview branches, promote branches to production, manage branch-specific schemas) through MCP tools that call the Supabase Management API. Implements branching tool group with operations for branch creation from production schema, branch promotion with data migration, and branch deletion. The implementation integrates with Supabase's branching system to provide isolated preview databases for testing schema changes and data operations before production deployment, with automatic schema synchronization and data seeding capabilities.

Implements a feature groups configuration pattern that selectively enables tool categories (account management, database operations, storage, edge functions, branching, cost management) per MCP server deployment context. The architecture uses configuration objects that specify which tool groups to enable, allowing different deployment scenarios (hosted HTTP endpoint, npm package, CLI) to expose different capability sets based on security and operational requirements. This pattern enables fine-grained access control without code duplication, using a shared tool registry that tools register themselves against.

Provides cost tracking and usage monitoring tools that query Supabase Management API for project usage metrics (database size, storage usage, function invocations, API requests). Implements cost management tool group that retrieves billing information, usage statistics, and cost projections. The implementation aggregates usage data from multiple Supabase services and presents it through a unified MCP interface, enabling AI assistants to provide cost-aware recommendations and help teams optimize resource usage.

Implements a TypeScript monorepo using pnpm workspaces with three npm packages: @supabase/mcp-server-supabase (Management API server), @supabase/mcp-utils (shared utilities), and @supabase/mcp-server-postgrest (PostgREST API server). The @supabase/mcp-utils package provides foundational abstractions including platform interface definitions, API client implementations, tool registry patterns, and testing utilities. The platform abstraction layer decouples transport mechanisms (HTTP, stdio, programmatic) from tool implementations, enabling code reuse across distribution channels. Uses Biome for code formatting and linting with pnpm workspace filtering for build orchestration.