Supabase MCP Server Integration Utility

Facilitate connectivity between your Supabase deployments and advanced AI assistants (e.g., Cursor, Claude, Windsurf).

The Model Context Protocol (MCP) establishes a standardized communication framework for Large Language Models (LLMs) to interact with external platforms like Supabase. This tool establishes a direct conduit between the AI entity and your Supabase project, empowering it to execute tasks such as schema modification, configuration retrieval, and executing arbitrary queries.

Essential Prerequisites

Ensure that Node.js is present on your operating environment. You can confirm installation status with:

shell node -v

If absent, installation binaries are available from nodejs.org.

Configuration Steps

1. Provisioning a Personal Access Token (PAT)

Navigate to your Supabase settings to generate a personal access token. Assign a descriptive label (e.g., "Cursor MCP Server").

This token is crucial for authenticating the MCP server against your Supabase tenancy. Immediately copy the token value, as it will be obscured upon exit from the creation screen.

2. Configuring the MCP Client Endpoint

Subsequently, configure your chosen MCP client (such as Cursor) to utilize this server endpoint. Typically, this involves injecting configuration data in JSON format:

{ "mcpServers": { "supabase": { "command": "npx", "args": [ "-y", "@supabase/mcp-server-supabase@latest", "--access-token", "" ] } } }

Substitute <personal-access-token> with the credential generated previously. As an alternative to embedding the token, you may set the SUPABASE_ACCESS_TOKEN environment variable; remember to relaunch the MCP client afterward. This method aids in keeping sensitive credentials out of repository history.

The utility supports supplementary launch parameters:

• --project-ref: Narrows the server's operational scope to a single, specified project. Refer to the project scoped mode section.
• --read-only: Constrains the server solely to data retrieval operations. See read-only mode.

If operating on a Windows system, command prefixing is necessary (detailed under windows). If your MCP client does not natively support the JSON configuration structure, the direct invocation string is:

shell npx -y @supabase/mcp-server-supabase@latest --access-token=

Warning: Avoid executing this command directly; it is intended solely for invocation by the MCP client to initiate the server process. npx handles the automatic retrieval and execution of the most recent @supabase/mcp-server-supabase package from npm.

Windows Environment Considerations

For Windows users, prepend the execution instruction with cmd /c:

{ "mcpServers": { "supabase": { "command": "cmd", "args": [ "/c", "npx", "-y", "@supabase/mcp-server-supabase@latest", "--access-token", "" ] } } }

Alternatively, if Node.js executes within a Windows Subsystem for Linux (WSL) context:

{ "mcpServers": { "supabase": { "command": "wsl", "args": [ "npx", "-y", "@supabase/mcp-server-supabase@latest", "--access-token", "" ] } } }

Ensure the Node.js runtime is accessible via your system's PATH variable. For native Windows Node.js setups, update PATH by following these steps:

1. Locate the npm installation directory:

shell npm config get prefix

1. Append the resulting directory to your PATH variable:

shell setx PATH "%PATH%;"

1. Reinitialize the MCP client application.

Project Scoping Mode

By default, the server possesses credentials to manage all projects under your Supabase account. To limit its authority to a single entity, supply the --project-ref argument:

shell npx -y @supabase/mcp-server-supabase@latest --access-token= --project-ref=

Substitute <project-ref> with the unique identifier found in the project's general settings page (labeled Project ID).

Applying project scoping invalidates account-level operational tools (e.g., list_projects, list_organizations). The server's purview will then be restricted exclusively to the resources within the designated project.

Read-Only Operation Mode

To enforce safety by permitting only non-mutating database interactions, activate the --read-only flag:

shell npx -y @supabase/mcp-server-supabase@latest --access-token= --read-only

This constraint ensures that SQL executions, handled via a read-only PostgreSQL credential, cannot alter database structure or data. Note that this restriction only applies to database manipulation tools (execute_sql, apply_migration); administrative functions like create_project remain unaffected.

Available Tools

Advisory: This utility predates version 1.0; expect potential schema incompatibilities in future releases. LLMs dynamically adjust to exposed interfaces, mitigating practical user impact.

The following Supabase functionalities are exposed to the intelligent agent:

Account & Project Administration

Note: These functions are disabled if the server is configured for project scoping.

• list_projects: Enumerates all Supabase projects associated with the user.
• get_project: Retrieves specific metadata for a given project.
• create_project: Initiates the provisioning of a new Supabase project.
• pause_project: Suspends a project's operation.
• restore_project: Reinstates a paused project.
• list_organizations: Fetches a registry of all organizations the user belongs to.
• get_organization: Retrieves detailed information about a specified organization.

Data Layer Functions

• list_tables: Retrieves a roster of tables within specified database schemas.
• list_extensions: Shows currently active database extensions.
• list_migrations: Displays the history of applied database migrations.
• apply_migration: Executes a SQL migration script against the database. DDL operations should utilize this function for schema version control.
• execute_sql: Runs arbitrary, raw SQL queries. Best suited for data retrieval and non-schema-altering operations.
• get_logs: Fetches operational logs segmented by service type (api, postgres, edge functions, auth, storage, realtime) to aid in diagnostics and performance monitoring.

Serverless Compute Management (Edge Functions)

• list_edge_functions: Catalogs all extant Edge Functions within the project.
• deploy_edge_function: Pushes new or updated Edge Function code to the runtime environment.

Project Metadata Access

• get_project_url: Returns the primary API endpoint address for the project.
• get_anon_key: Retrieves the public (anonymous) API key.

Branching Capabilities (Subscription Dependent)

• create_branch: Establishes a distinct development branch, inheriting current production migrations.
• list_branches: Shows all current development branches.
• delete_branch: Removes a specified development branch.
• merge_branch: Integrates migrations and Edge Functions from a development branch into production.
• reset_branch: Reverts a development branch's migration state to a prior production checkpoint.
• rebase_branch: Synchronizes a development branch state against the latest production migration history.

Code Generation

• generate_typescript_types: Creates TypeScript interface definitions derived directly from the underlying database structure. This output can be saved externally for use in application code.

Financial Oversight (Paid Plans)

• get_cost: Estimates the operational expense for provisioning a new project or development branch.
• confirm_cost: Requires explicit user acknowledgment of projected costs before proceeding with project or branch creation.

Interoperability with Other MCP Servers

@supabase/mcp-server-postgrest

This companion server facilitates secure, direct REST API access for end-users of your application. Further documentation is available in the PostgREST server README.

Further Information

• Model Context Protocol Specification: In-depth exploration of MCP principles.
• Path to Production: Guidance on safely promoting changes through environments.

Developer Information

This repository leverages npm for dependency management and requires the current Long-Term Support (LTS) release of Node.js.

To clone and prepare the environment:

npm install --ignore-scripts

[!NOTE] On modern macOS installations, the installation of the transitive dependency libpg-query may fail unless the --ignore-scripts flag is included.

Licensing

This software is distributed under the terms of the Apache 2.0 License. See the LICENSE file for complete stipulations.