Supabase MCP Server

@supabase/mcp-server-supabase is Supabase’s official Model Context Protocol (MCP) server, letting AI assistants like Claude, Cursor, and Windsurf manage Supabase projects directly through natural-language tool calls. It wraps the Supabase Management API, pg-meta database introspection, and the Content API behind a typed set of MCP tools spanning account, branching, database, debugging, development, docs, edge-function, and storage operations.

The package ships both a ready-to-run stdio/HTTP server (bin: mcp-server-supabase, or the hosted https://mcp.supabase.com/mcp endpoint) and a programmatic API (createSupabaseMcpServer, createSupabaseMcpHandler, createToolSchemas) for teams that want to self-host the MCP endpoint or plug typed tool schemas into the Vercel AI SDK. Feature-group scoping, project-scoping, read-only mode, and an elicitation-based cost-confirmation flow for mutating operations (create_project, create_branch) let integrators control exactly what an AI assistant is allowed to do against a live Supabase account.

What You Get

• A hosted MCP endpoint (https://mcp.supabase.com/mcp) plus a local stdio/CLI binary (mcp-server-supabase) for zero-setup use in Cursor, Claude, Windsurf, and other MCP clients
• Eight tool groups — account, branching, database, debugging, development, docs, edge-function, and storage — covering the full Supabase project lifecycle
• A programmatic createSupabaseMcpServer/createSupabaseMcpHandler API for self-hosting the MCP endpoint behind your own auth
• createToolSchemas() for typed, statically-validated tool definitions when using Vercel AI SDK’s MCP client instead of dynamic discovery
• Built-in cost-confirmation elicitation for spend-incurring operations like creating a project or branch

Common Use Cases

• Letting an AI coding assistant create and manage Supabase branches while iterating on a feature
• Querying and modifying a Supabase Postgres schema from a chat interface without hand-writing SQL
• Debugging production issues by pulling project logs and advisories through an MCP-connected assistant
• Self-hosting a scoped, read-only MCP endpoint so an AI tool can only inspect — never mutate — a production project

Under The Hood

Architecture server.ts composes createMcpServer from @supabase/mcp-utils, wiring together eight tool modules under src/tools/ (account, branching, database-operation, debugging, development, docs, edge-function, storage-tools) that each return a ToolDefs map consumed by writeToolSet. A platform abstraction (src/platform/types.ts, api-platform.ts) decouples tool logic from the concrete Supabase Management API client, so the same tool surface can run against createSupabaseApiPlatform or a test/mock platform. The transports layer (src/transports/http.ts, stdio.ts) exposes two entry points built on that shared server factory — stdio for local CLI/MCP-client spawn, and an HTTP handler (createSupabaseMcpHandler) for self-hosting. Cost-confirmation (cost-confirmation.ts) adds an HMAC-signed requestState codec so mutating tools like create_project and create_branch can gate on user confirmation across both the classic confirm_cost_id flow and newer per-request form-elicitation clients. Changing the core tool-registration abstraction would ripple through all eight tool modules and both transports.

Tech Stack TypeScript compiled with tsup into dual CJS/ESM output, Zod v4 for input/output schema validation on every tool, @supabase/mcp-utils and @modelcontextprotocol/server/client for the MCP protocol layer, openapi-fetch against a generated management-api/types.ts for typed Supabase Management API calls, graphql/gqlmin for the pg-meta/GraphQL surface, @electric-sql/pglite for in-memory Postgres in tests, vitest across unit/e2e/integration projects, Biome for lint and format, and a pnpm workspace with dependency catalogs shared across the monorepo’s three packages.

Code Quality The package carries a comprehensive suite of *.test.ts files covering pure logic (log-window resolution, password generation, edge-function parsing) alongside separate unit/e2e/integration vitest projects. Errors are explicit and typed via Zod schemas rather than swallowed silently. tsconfig extends @total-typescript/tsconfig’s strict base, and Biome enforces consistent formatting and linting via a dedicated CI workflow, with a separate GitHub Actions workflow running the test suite on every change.

API Design The package exposes a deliberately dual surface: a zero-config CLI/stdio binary for MCP-client users and a programmatic createSupabaseMcpServer/createSupabaseMcpHandler API for self-hosters, with createToolSchemas() additionally giving Vercel AI SDK consumers typed static tool schemas instead of relying on dynamic MCP discovery. Feature-group scoping (features, projectScoped, readOnly options or URL params) lets integrators trim the tool surface without forking the package. Cost-confirmation elicitation is opt-in and backward compatible, preserving the original confirm_cost_id flow for clients that lack form capability. Getting started with the common path — pointing an MCP client at the hosted endpoint — requires no code at all; self-hosting requires supplying a SupabasePlatform implementation and, for cost confirmation, a 32-plus-byte HMAC key.