Supabase MCP

What supabase-community/supabase-mcp does

The supabase-community/supabase-mcp MCP server gives MCP-compatible AI assistants access to Supabase project operations. Its documented use cases include managing database tables, retrieving configuration, and querying project data. The server is intended for connecting an assistant to a project through Supabase authentication rather than manually exposing separate database credentials to the model.

The project belongs in the 🗄️ Databases category. It can also serve as a foundation for applications that need to expose Supabase operations through an AI SDK MCP client or a custom HTTP endpoint.

How it works

The hosted service is available at https://mcp.supabase.com/mcp over HTTP. An MCP client connects to that URL, and the client prompts the user to sign in to Supabase and select the organization containing the target project. The connection can be narrowed with URL options such as project_ref, read_only=true, and a comma-separated features value.

The supabase-community/supabase-mcp package also provides JavaScript APIs for embedding the server in an application. createToolSchemas() supplies schemas for use with Vercel AI SDK's MCP client, including inferred TypeScript input and output types. createSupabaseMcpHandler() can expose the tools from an HTTP endpoint that you operate. Per-request credentials require creating and closing handlers around each request; a shared service credential can use a long-lived handler.

Setup and configuration

For the hosted deployment, add the HTTP MCP endpoint to the configuration format required by your client. Supabase provides a dashboard MCP connection tab and an interactive URL builder for generating configuration options. Review Supabase's MCP security guidance before granting an AI assistant access to a project.

Local Supabase CLI environments expose the server at http://localhost:54321/mcp. Self-hosted Supabase installations have their own enablement procedure. Both local and self-hosted modes currently provide a limited subset of tools and do not provide OAuth 2.1.

When self-hosting the endpoint in Node.js, the project uses @modelcontextprotocol/node alongside the Supabase package. The handler supports the current protocol revision and rejects clients that only support the older 2025-era protocol.

Tools and capabilities

The supabase-community/supabase-mcp MCP server supports feature filtering, project-scoped schemas, and read-only schemas. Project-scoped mode removes project_id from tool inputs and excludes account-level tools when a project reference is already configured. Read-only mode removes mutating tools. These settings can be applied through the server URL and mirrored in createToolSchemas().

The full tool inventory and feature groups are maintained in Supabase's MCP documentation rather than enumerated in the repository excerpt.

The package supports optional observability through an observer passed to createSupabaseMcpServer. Observers can receive bounded lifecycle results and Supabase facts. Observation is disabled when no observer is supplied, and observer failures do not change request behavior.

Limitations and notes

MCP tool results do not include structuredContent; clients such as the AI SDK must parse JSON from the text content. Local CLI and self-hosted deployments have fewer tools than the hosted service and lack OAuth 2.1. A handler's close() method aborts in-flight exchanges, so applications serving streaming responses should close it after the response finishes. Connecting an AI assistant to a Supabase project carries security risks, so access scope and write permissions should be reviewed before deployment.