Supabase Interface Gateway via MCP

Establish connections between your Supabase environments and intelligent systems like Cursor, Claude, Windsurf, and other AI assistants.

The Model Context Protocol (MCP) is the standardized framework governing LLM interactions with external infrastructures such as Supabase. It directly links AI agents to your Supabase instance, empowering them to execute operations like schema modification, configuration fetching, and executing data queries. Refer to the comprehensive suite of tools for specifics.

Prerequisites for Operation

Ensure you have Node.js installed locally. Verification can be performed using this command:

node -v

Should Node.js be absent, download the requisite installer from nodejs.org.

Deployment Procedure

1. Generating a Personal Credential (PAT)

Initially, navigate to your Supabase account tokens settings and generate a new personal access token. Assign it a descriptive label, such as "Cursor MCP Gateway".

This credential authenticates the MCP server with your Supabase credentials. Immediately capture the token, as it will not be displayed again.

2. Configuring the MCP Client

Subsequently, update your MCP client (e.g., Cursor) configuration to utilize this newly established server. Most MCP clients expect configuration in the following JSON structure:

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

Substitute <personal-access-token> with the token generated in Step 1. Optionally, you can bypass including --access-token by setting the environment variable SUPABASE_ACCESS_TOKEN to your token value (a subsequent MCP client restart will be necessary). This method safeguards your secret by preventing its inclusion in repository source code.

The following optional parameters are supported:

• --project-ref: Designates the specific organizational project to scope the server's activity. Consult the project-scoped operation section for details.
• --read-only: Enforces read-only constraints on all applicable operations. See the restricted access documentation.

If operating within a Windows environment, you must precede the command. If your MCP client does not process JSON configurations, the requisite direct command-line invocation is:

npx -y @supabase/mcp-server-supabase@latest --access-token=<personal-access-token>

Warning: Avoid direct execution of this command; it is intended solely for initiation by your MCP client. npx manages the dynamic retrieval and immediate execution of the most current MCP server package from the npm registry.

Windows Environment Specifics

For Windows users, prepend the command structure with cmd /c:

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

or utilize wsl if Node.js execution occurs within the Windows Subsystem for Linux environment:

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

Ensure Node.js is accessible via your system's PATH variable. If running Node.js natively on Windows, configure the PATH by executing these terminal commands sequentially:

1. Ascertain the npm installation directory prefix:

shell npm config get prefix

1. Append this resolved directory to your system's PATH variable:

shell setx PATH "%PATH%;<path-to-dir>"

1. Relaunch your MCP client application.

Project Scoping Mode

By default, the MCP server possesses access rights across all organizations and projects linked to your Supabase account. To confine the server's operational scope to a singular project, incorporate the --project-ref directive into the command line:

npx -y @supabase/mcp-server-supabase@latest --access-token=<personal-access-token> --project-ref=<project-ref>

Substitute <project-ref> with the identifier of your target project. This ID is located under Project ID within your Supabase project general settings.

Upon activating project confinement, management functions scoped to the entire account, such as list_projects and list_organizations, become inaccessible. The server will then be restricted exclusively to the resources of the specified project.

Read-Only Operational Mode

If the requirement is to limit the Supabase MCP server to strictly retrieval operations, employ the --read-only flag in the execution instruction:

npx -y @supabase/mcp-server-supabase@latest --access-token=<personal-access-token> --read-only

This setting actively prohibits any data modification activities within your databases by routing SQL execution through a read-only PostgreSQL credential. Note that this restriction only impacts database interaction tools (execute_sql and apply_migration) and does not extend to project lifecycle tools (e.g., create_project or create_branch).

Available Tools

Advisory: This server is currently designated as pre-1.0; be prepared for potential backward-incompatible modifications across subsequent releases. LLMs are designed to dynamically adapt to the current toolset, mitigating most user impact.

The following Supabase capabilities are exposed to the Language Model:

Organizational and Project Administration

Note: These administrative functions are deactivated if the server is configured for project-specific operation.

• list_projects: Retrieves a catalog of all Supabase projects associated with the authenticated user.
• get_project: Fetches detailed attributes for a specified project.
• create_project: Provisions a novel Supabase project instance.
• pause_project: Suspends operations for an existing project.
• restore_project: Reinstates a paused project.
• list_organizations: Generates a list of all organizations to which the user belongs.
• get_organization: Retrieves specific metadata for an organization.

Data Layer Operations

• list_tables: Enumerates all accessible tables within designated database schemas.
• list_extensions: Lists all installed database extensions.
• list_migrations: Returns the sequence of applied database migrations.
• apply_migration: Commits a SQL migration script to the database schema. SQL provided here is tracked internally, making it the appropriate choice for Data Definition Language (DDL) changes.
• execute_sql: Runs arbitrary, raw SQL queries against the database. This is intended for routine data retrieval and manipulation (DML) operations that do not alter structure.
• get_logs: Retrieves operational logs segmented by service type (api, postgres, edge functions, auth, storage, realtime). Useful for diagnostic and performance monitoring by the LLM.

Edge Function Orchestration

• list_edge_functions: Catalogues all deployed Edge Functions within the project context.
• deploy_edge_function: Installs or updates an Edge Function deployment. Facilitates automated deployment of new or modified function code.

Endpoint Configuration Retrieval

• get_project_url: Supplies the primary API endpoint URL for the project.
• get_anon_key: Extracts the public, anonymous access key for the project.

Branching Workflow (Subscription Required)

• create_branch: Initiates a new development branch, seeding it with current production migration state.
• list_branches: Shows all existing development branches.
• delete_branch: Permanently removes a specified development branch.
• merge_branch: Integrates migrations and Edge Functions from a development branch into the main production stream.
• reset_branch: Rolls back the migration state of a development branch to a prior committed version.
• rebase_branch: Synchronizes a development branch against the latest production state to resolve schema divergence.

Schema Productivity

• generate_typescript_types: Creates TypeScript type definitions derived directly from the database schema. LLMs can persist this output to a local file for integration into codebases.

Financial Accountability

• get_cost: Determines the projected operational expenditure for a prospective new project or branch under a specific organization.
• confirm_cost: Explicitly secures user acknowledgment of the calculated costs prior to provisioning any new project or branch resources.

Alternative MCP Servers

@supabase/mcp-server-postgrest

The PostgREST MCP server enables your application's end-users to interact with the backend database via standard RESTful API endpoints. Further specifics are available in its dedicated project documentation.

Supplementary Information

• Model Context Protocol Documentation: Explore the full scope of MCP capabilities.
• Pathway to Production: Guidance on securely promoting changes from development stages to live environments.

Developer Guidelines

This repository utilizes npm for dependency management, mandating the current LTS release of Node.js.

To clone and prepare the environment, execute:

npm install --ignore-scripts

[!NOTE] On recent macOS versions, installing the transient dependency libpg-query might fail without the --ignore-scripts flag.

Licensing

This software is released under the Apache 2.0 License. Refer to the LICENSE file for comprehensive terms.