Supabase MCP

What supabase-community/supabase-mcp does

The supabase-community/supabase-mcp MCP server exposes Supabase capabilities through the Model Context Protocol. AI assistants can use it to work with Supabase projects, including managing tables, querying data, and retrieving configuration. The repository describes the project as the official Supabase MCP server and provides a hosted endpoint for MCP clients.

Available tools and configuration details are maintained in the Supabase MCP documentation. The README specifically identifies database and documentation feature groups, while the complete tool list is linked externally rather than reproduced in the repository.

How it works

The default connection uses HTTP at https://mcp.supabase.com/mcp. An MCP client connects to that endpoint and prompts the user to authenticate with Supabase. During setup, the user selects the organization containing the project to use.

The endpoint accepts URL options that control the exposed tool set. project_ref binds the connection to one project. read_only=true excludes mutating tools, and features selects feature groups such as database and docs. These options can be combined, for example by connecting with a project reference, read-only mode, and a restricted feature list.

The package also supports embedding the server in an application. Its createSupabaseMcpHandler() export serves the tools over HTTP, while createToolSchemas() provides schemas for use with the Vercel AI SDK MCP client. Tool results do not include MCP structuredContent; the AI SDK instead parses JSON from the returned content text.

Setup and configuration

For a hosted Supabase project, add the HTTP endpoint to the MCP client’s configuration. Most clients use a structure equivalent to an mcpServers entry with the server URL. Supabase also provides an MCP connection tab and an interactive URL builder for generating project-specific configuration.

Cursor, Claude, Windsurf, and other MCP-capable assistants are named as supported client targets. If a client is not covered by Supabase’s setup documentation, its MCP configuration format should be used with the same endpoint information.

Local Supabase CLI deployments expose the server at http://localhost:54321/mcp. Self-hosted Supabase installations have a separate enablement process. Both local and self-hosted modes currently provide a limited tool subset and do not provide OAuth 2.1.

Tools and capabilities

The supabase-community/supabase-mcp MCP server supports the following documented capability areas:

• Manage Supabase tables.
• Query Supabase data.
• Fetch project configuration.
• Restrict tools to selected feature groups.
• Exclude mutating tools with read-only mode.
• Use project-scoped schemas that omit project_id from tool inputs.

The AI SDK integration can generate static tool schemas with client-side validation and inferred TypeScript input and output types. The package also exports an HTTP handler for self-hosted deployments, where the application supplies the platform and can provide credentials per request.

Limitations and notes

Review Supabase’s MCP security guidance before granting an AI assistant access to a project. Local CLI and self-hosted environments have fewer tools than the hosted service and lack OAuth 2.1. The self-hosted handler supports the current protocol revision and rejects clients that only speak the 2025-era protocol.

When embedding the handler, request-specific credentials require a handler created for that request. A shared, long-lived handler can instead use a shared platform credential, such as a service-account token. The README also notes that the Node HTTP adapter used in the self-hosting example is not included as a dependency and must be installed separately.

Getting started with this supabase-community/supabase-mcp MCP server

Always refer to the official documentation for the most accurate and up-to-date information.