Supabase MCP server

The Supabase MCP Server acts as a connector between your Supabase projects and AI assistants like Cursor, Claude, and Windsurf using the Model Context Protocol (MCP). This allows AI assistants to interact directly with your Supabase projects to perform tasks such as managing database tables, querying data, and accessing project configurations.

Prerequisites

You need Node.js (active LTS or newer) installed on your machine. Verify your installation with:

node -v

If you don't have Node.js 22+ installed, download it from nodejs.org.

Installation and Setup

Create a Personal Access Token

1. Go to your Supabase settings and create a personal access token
2. Give it a descriptive name like "Cursor MCP Server"
3. Copy the token immediately as you won't be able to see it again

Configure Your MCP Client

Configure your MCP client (such as Cursor) to use this server. Most MCP clients store the configuration as JSON:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

Replace <personal-access-token> with your token from step 1. You can also set this environment variable globally on your machine to keep it out of version control.

Configuration Options

The following options are available:

• --read-only: Restricts the server to read-only queries and tools (recommended)
• --project-ref: Scopes the server to a specific project (recommended)
• --features: Specifies which tool groups to enable

Windows-Specific Setup

On Windows, prefix the command with cmd /c:

{
  "mcpServers": {
    "supabase": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

Or with wsl if running Node.js inside WSL:

{
  "mcpServers": {
    "supabase": {
      "command": "wsl",
      "args": [
        "npx",
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

Ensure Node.js is in your PATH environment variable. If running Node.js natively on Windows:

1. Get the npm path:

   npm config get prefix
   

2. Add to your PATH:

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

3. Restart your MCP client

Security Configuration

Project Scoped Mode

It's recommended to restrict the server to a specific project using the --project-ref flag:

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

Find your project reference ID under "Project ID" in your Supabase project settings.

Read-Only Mode

Restrict the server to read-only operations using the --read-only flag:

npx -y @supabase/mcp-server-supabase@latest --read-only

This prevents write operations by executing SQL as a read-only Postgres user and disables all mutating tools.

Feature Groups

Customize which tool groups are available using the --features flag:

npx -y @supabase/mcp-server-supabase@latest --features=database,docs

Available groups include: account, docs, database, debugging, development, functions, storage, and branching.

Available Tools

Account Tools

• list_projects: Lists all Supabase projects
• get_project: Gets project details
• create_project: Creates a new project
• pause_project/restore_project: Pauses or restores a project
• list_organizations/get_organization: Organization management
• get_cost/confirm_cost: Cost-related operations

Knowledge Base Tools

• search_docs: Searches Supabase documentation

Database Tools

• list_tables: Lists all tables within specified schemas
• list_extensions: Lists database extensions
• list_migrations: Lists migrations
• apply_migration: Applies SQL migrations
• execute_sql: Executes raw SQL

Debugging Tools

• get_logs: Gets logs by service type
• get_advisors: Gets advisory notices

Development Tools

• get_project_url: Gets API URL
• get_anon_key: Gets anonymous API key
• generate_typescript_types: Generates TypeScript types

Edge Functions Tools

• list_edge_functions: Lists Edge Functions
• get_edge_function: Retrieves function contents
• deploy_edge_function: Deploys new functions

Branching Tools (requires paid plan)

• create_branch/list_branches/delete_branch: Branch management
• merge_branch/reset_branch/rebase_branch: Branch operations

Storage Tools

• list_storage_buckets: Lists storage buckets
• get_storage_config/update_storage_config: Storage configuration

Security Best Practices

To mitigate security risks:

• Use with development projects, not production
• Keep internal - don't give to customers
• Use read-only mode when possible
• Enable project scoping to limit access
• Use branching features for testing
• Limit tool groups to reduce attack surface
• Always review tool calls before executing them

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "supabase" '{"command":"npx","args":["-y","@supabase/mcp-server-supabase@latest","--read-only","--project-ref=<project-ref>"],"env":{"SUPABASE_ACCESS_TOKEN":"<personal-access-token>"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "supabase": {
            "command": "npx",
            "args": [
                "-y",
                "@supabase/mcp-server-supabase@latest",
                "--read-only",
                "--project-ref=<project-ref>"
            ],
            "env": {
                "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "supabase": {
            "command": "npx",
            "args": [
                "-y",
                "@supabase/mcp-server-supabase@latest",
                "--read-only",
                "--project-ref=<project-ref>"
            ],
            "env": {
                "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect