How to Install Supabase MCP Server

The landscape of software development is rapidly evolving, with Artificial Intelligence (AI) playing an increasingly significant role. AI assistants and Large Language Models (LLMs) like OpenAI's GPT series, Anthropic's Claude, and specialized tools like Cursor are becoming powerful partners in coding, debugging, and system management. However, for these AI assistants to interact effectively with specific backend services, a standardized communication protocol is essential. This is where the Model Context Protocol (MCP) comes in.

Supabase, the popular open-source Firebase alternative, provides a rich suite of tools for building applications, including databases, authentication, storage, and edge functions. To empower AI assistants to directly interact with and manage Supabase projects, the Supabase community has developed the Supabase MCP Server.

This server acts as a crucial bridge, implementing the MCP standard to allow AI assistants to connect securely to your Supabase account and projects. Once connected, the AI can perform a wide array of tasks, from listing tables and executing SQL queries to managing project settings and even handling database migrations, all guided by natural language prompts or the AI's internal logic.

This article provides a detailed walkthrough on how to install and configure the Supabase MCP Server, based entirely on the information provided in the official supabase-community/supabase-mcp GitHub repository. We will cover prerequisites, the core setup process, platform-specific considerations (particularly for Windows), enabling read-only mode for enhanced safety, and an overview of the powerful tools this server makes available to your AI assistant.

Tired of Postman? Want a decent postman alternative that doesn't suck?

Apidog is a powerful all-in-one API development platform that's revolutionizing how developers design, test, and document their APIs.

Unlike traditional tools like Postman, Apidog seamlessly integrates API design, automated testing, mock servers, and documentation into a single cohesive workflow. With its intuitive interface, collaborative features, and comprehensive toolset, Apidog eliminates the need to juggle multiple applications during your API development process.

Whether you're a solo developer or part of a large team, Apidog streamlines your workflow, increases productivity, and ensures consistent API quality across your projects.

What is the Model Context Protocol (MCP)?

https://github.com/supabase-community/supabase-mcp

Before diving into the installation, it's helpful to understand the role of MCP. As described in the repository, the Model Context Protocol standardizes how Large Language Models (LLMs) communicate with external services like Supabase. It defines a common language and structure for requests and responses, enabling AI tools to discover and utilize the capabilities offered by connected services without needing bespoke integrations for each one. The Supabase MCP Server is an implementation of this standard specifically tailored for the Supabase ecosystem.

Prerequisites: Preparing Your Environment

The primary prerequisite for running the Supabase MCP Server is having Node.js installed on your machine. Node.js is a JavaScript runtime environment that allows you to execute JavaScript code outside of a web browser, and it comes bundled with npm (Node Package Manager), which includes the npx tool used in the setup process.

You can verify if Node.js is installed and check its version by opening your terminal or command prompt and running:

node -v

If this command returns a version number (e.g., v18.18.0), you're good to go. If it returns an error or is not recognized, you need to install Node.js. You can download the official installer for your operating system from the Node.js website: nodejs.org. It's generally recommended to install the LTS (Long-Term Support) version for stability.

Installation and Setup: Connecting Supabase to Your AI

The setup process involves two main steps: generating a Supabase Personal Access Token (PAT) for authentication and configuring your chosen MCP client (like Cursor, Claude, Windsurf, etc.) to use the Supabase MCP Server.

Step 1: Generate a Supabase Personal Access Token (PAT)

The MCP server needs to authenticate with your Supabase account to access your projects and perform actions on your behalf. This is done using a Personal Access Token (PAT).

1. Navigate to your Supabase account settings page in your web browser. You can usually find this by logging into your Supabase dashboard and accessing the account or profile section (the exact location might vary slightly based on the Supabase UI).
2. Find the section for generating Personal Access Tokens (often under "Access Tokens" or "API Keys").
3. Create a new token. It's crucial to give it a descriptive name that clearly indicates its purpose, for example, "Cursor MCP Server" or "Claude MCP Integration". This helps you manage your tokens later.
4. Generate the token. Crucially, Supabase will only show you the token value once upon creation. Make sure to copy this token immediately and store it securely (e.g., in a password manager). You will need it in the next step. Treat this token like a password; anyone who has it can potentially access and manage your Supabase projects through the MCP server.

Step 2: Configure Your MCP Client

The Supabase MCP Server is not typically run as a standalone, persistent service. Instead, it's designed to be invoked by your MCP client application (like Cursor) when needed. Most MCP clients use a JSON configuration format to define how to connect to various MCP servers.

The standard JSON structure provided in the supabase-mcp repository looks like this:

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

Let's break down this configuration:

• "mcpServers": The top-level key indicating definitions for MCP servers.
• "supabase": A unique identifier for this specific server configuration (you could potentially configure multiple different MCP servers).
• "command": The base command to execute. Here, it's "npx". npx is a tool included with npm that allows you to execute Node.js packages without having to install them globally. It automatically downloads the specified package if it's not already present and runs it.
• "args": An array of arguments passed to the command.
  • "-y": A flag for npx that automatically confirms any prompts, ensuring the command runs without interactive input.
  • "@supabase/mcp-server-supabase@latest": This is the core instruction. It tells npx to fetch and run the latest version of the Supabase MCP Server package published on npm. Using @latest ensures you generally benefit from the newest features and fixes, although note the pre-1.0 status mentioned later.
  • "--access-token": The command-line flag used by the server to receive the authentication token.
  • "<personal-access-token>": This is where you paste the actual Personal Access Token you generated in Step 1. Replace the placeholder <personal-access-token> with your copied token string.

You will need to find where your specific MCP client (Cursor, Claude, etc.) stores its configuration (often a JSON file like settings.json or within its UI settings) and add or modify the mcpServers section accordingly.

Alternative: Using Environment Variables for Security

Hardcoding your PAT directly into a configuration file might pose a security risk, especially if you plan to commit this configuration file to a version control system like Git.

As an alternative, the Supabase MCP Server supports reading the access token from an environment variable named SUPABASE_ACCESS_TOKEN. If you choose this method:

1. Set the SUPABASE_ACCESS_TOKEN environment variable in your system or shell environment to the value of your PAT. The method for setting environment variables varies depending on your operating system and shell (e.g., using export in bash/zsh, set or setx in Windows Command Prompt, or system environment variable settings).

2. Modify the MCP client JSON configuration to omit the --access-token and token value from the args array:

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

3. Important: After setting the environment variable, you will likely need to restart your MCP client application for it to pick up the new variable.

Using the environment variable is generally considered a more secure practice for handling sensitive credentials.

Note on Direct Execution: The repository explicitly states: "Note: Do not run this command directly - this is meant to be executed by your MCP client in order to start the server." The command npx -y @supabase/mcp-server-supabase@latest --access-token=<your-pat> is the underlying instruction, but the client manages its lifecycle (starting and stopping it as needed).

Platform Specifics: Windows Configuration

Running Node.js applications via command-line invocation can sometimes require adjustments on Windows. The supabase-mcp repository provides specific instructions for Windows users:

1. Prefixing the Command: You might need to prefix the npx command depending on your environment:

   • Standard Windows (cmd.exe/PowerShell): Prefix the command with cmd /c. The JSON configuration would look like this:

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

   • Windows Subsystem for Linux (WSL): If you are running Node.js inside WSL, prefix the command with wsl:

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

     (Note: Ensure Node.js is installed within your WSL distribution in this case).

2. Ensuring Node.js is in PATH (Native Windows): If you installed Node.js natively on Windows but npx isn't found, you might need to ensure its directory is included in your system's PATH environment variable.

   • Find the npm installation directory by running: npm config get prefix
   • Copy the path returned by this command.
   • Add this directory to your system PATH. You can do this via System Properties -> Environment Variables, or by using the setx command in an administrative command prompt (replace <path-to-dir> with the actual path): setx PATH "%PATH%;<path-to-dir>"
   • Restart your MCP client after modifying the PATH variable for the changes to take effect.

Safety First: Enabling Read-Only Mode

Giving an AI direct access to manage your Supabase projects, especially databases, carries inherent risks. An incorrectly understood instruction or an AI hallucination could potentially lead to unintended data modification or deletion.

To mitigate this risk, the Supabase MCP Server offers a crucial read-only mode. When enabled, this mode prevents the server from performing write operations on your databases via specific tools.

To enable read-only mode, add the --read-only flag to the args array in your MCP client's JSON configuration:

{
  "mcpServers": {
    "supabase": {
      "command": "npx", // or "cmd", "wsl" as needed
      "args": [
        // other args like "-y", "/c" if applicable
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--access-token",
        "<personal-access-token>", // Or omit if using env var
        "--read-only" // Add this flag
      ]
    }
  }
}

Important Limitations: According to the documentation, the --read-only flag works by executing SQL via the execute_sql and apply_migration tools as a specific read-only Postgres user. However, it explicitly does not restrict other potentially destructive or cost-incurring actions like creating new projects (create_project) or managing branches (create_branch, delete_branch, etc.). Therefore, while read-only mode adds a significant layer of safety for database queries, careful consideration and monitoring are still essential.

Empowering AI: Available Tools

Once configured, the Supabase MCP Server exposes a rich set of tools that the connected AI assistant can utilize. These tools are the functions the AI can call upon to interact with your Supabase resources. The repository lists the following available tools, categorized for clarity:

Project Management:

• list_projects: Retrieves a list of all Supabase projects accessible by the authenticated user.
• get_project: Fetches detailed information about a specific project.
• create_project: Creates a new Supabase project (subject to cost confirmation).
• pause_project: Pauses an active Supabase project.
• restore_project: Restores a paused Supabase project.
• list_organizations: Lists all organizations the user is a member of.
• get_organization: Gets details about a specific organization.

Database Operations:

• list_tables: Lists all tables within specified schemas in a project's database.
• list_extensions: Lists all installed Postgres extensions in the database.
• list_migrations: Shows the database migration history tracked by Supabase.
• apply_migration: Applies a SQL migration script to the database. This is intended for Data Definition Language (DDL) operations (like creating/altering tables) and tracks the migration within Supabase.
• execute_sql: Executes arbitrary SQL queries against the database. This is intended for standard data queries (SELECT, INSERT, UPDATE, DELETE) that do not alter the database schema.
• get_logs: Fetches logs for various Supabase services (API, Postgres, Edge Functions, Auth, Storage, Realtime), useful for debugging and monitoring.

Project Configuration:

• get_project_url: Retrieves the API URL for a specific project.
• get_anon_key: Gets the anonymous API key for a project, often used for client-side access.

Branching (Experimental, Requires Paid Plan): Supabase offers a database branching feature (typically on paid plans) for safer development workflows. The MCP server provides tools to manage these branches:

• create_branch: Creates a new development branch, inheriting migrations from the production branch.
• list_branches: Lists existing development branches.
• delete_branch: Deletes a development branch.
• merge_branch: Merges changes (migrations, edge functions) from a development branch into the production branch.
• reset_branch: Resets a development branch to a previous migration state.
• rebase_branch: Updates a development branch with the latest changes from the production branch to resolve potential migration conflicts.

Development Tools:

• generate_typescript_types: Generates TypeScript type definitions based on the current database schema. The AI can save this output to a file for use in code generation or type checking.

Cost Confirmation: Creating new resources often incurs costs. To prevent accidental charges:

• get_cost: Estimates the cost of creating a new project or branch within a specific organization.
• confirm_cost: A mandatory step where the AI must confirm the user understands the associated costs before proceeding with create_project or create_branch.

Important Note on Versioning: The repository clearly states that the server is pre-1.0, meaning breaking changes between versions are possible. However, it also suggests that LLMs should generally be able to adapt to the available tools, minimizing disruption for most users. Still, it's wise to be aware of potential changes when relying on this integration.

Related Servers and Resources

The supabase-community organization also offers other related tools. The README specifically mentions the @supabase/mcp-server-postgrest MCP server, which serves a different purpose: allowing your application's end-users (not just you, the developer) to interact with your app's data via a PostgREST-based REST API through an AI assistant. Details can be found in its own project README.

Furthermore, the main README links to valuable external resources:

• Model Context Protocol: For a deeper understanding of the MCP standard itself.
• From development to production: A guide on safely promoting database changes, relevant when using tools like apply_migration or branching features.

Conclusion

The Supabase MCP Server represents a significant step forward in integrating AI capabilities directly into the backend development workflow. By following the installation steps outlined in the official repository – obtaining a PAT, configuring your AI client (handling Windows specifics if necessary), and considering the use of read-only mode for safety – you can unlock a powerful new paradigm.

This server empowers AI assistants to become active participants in managing your Supabase projects, querying data, applying schema changes, generating typed code, and much more, all governed by the standardized Model Context Protocol. While currently in a pre-1.0 stage, its potential to streamline development, automate tasks, and enhance debugging is immense. As AI continues to evolve, tools like the Supabase MCP Server will be instrumental in harnessing its full potential within specific technology ecosystems. Remember to handle your Personal Access Token securely and be mindful of the capabilities you grant your AI assistant.