Supabase MCP server

Connects directly to Supabase projects for managing databases, executing SQL queries, applying migrations, and handling configurations through natural language commands.
Back to servers
Setup instructions
Provider
Supabase
Release date
Apr 01, 2025
Language
TypeScript
Package
Stats
330.4K downloads
1.8K stars

The Supabase MCP Server enables you to connect your Supabase projects with AI assistants like Cursor, Claude, and Windsurf through the Model Context Protocol (MCP). This standardized protocol allows AI assistants to interact directly with your Supabase project to perform tasks such as managing tables, fetching configurations, and querying data.

Prerequisites

You will need Node.js installed on your machine. You can verify your installation by running:

node -v

If Node.js is not installed, you can download it from nodejs.org.

Installation and Setup

1. Create a Personal Access Token (PAT)

Go to your Supabase settings and create a personal access token. Give it a descriptive name like "Cursor MCP Server".

This token will authenticate the MCP server with your Supabase account. Make sure to copy it after creation as you won't be able to view it again.

2. Configure Your MCP Client

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

{
  "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 and <project-ref> with your project ID.

Configuration Options

The server accepts several important configuration flags:

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

Windows Configuration

On Windows, you'll need to 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 you're 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 available in your PATH environment variable.

Security Best Practices

Project Scoped Mode

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 ID in your Supabase project settings under "Project ID".

Read-only Mode

Enable read-only mode to restrict operations to read-only queries:

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

This prevents write operations by executing SQL as a read-only Postgres user.

Feature Groups

Customize which tool groups are available to the LLM:

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

Available groups include:

  • account: Project and organization management
  • docs: Documentation search
  • database: Database operations
  • debug: Logs and advisories
  • development: Project URL, API keys, TypeScript types
  • functions: Edge Function management
  • storage: Storage bucket management
  • branching: Database branching (requires paid plan)

Available Tools

Database Tools

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

Knowledge Base Tools

  • search_docs: Searches Supabase documentation for up-to-date information

Debug Tools

  • get_logs: Retrieves logs by service type
  • get_advisors: Gets advisory notices for security or performance issues

Development Tools

  • get_project_url: Gets the API URL for a project
  • get_anon_key: Retrieves the anonymous API key
  • generate_typescript_types: Generates TypeScript types from your schema

Security Recommendations

To minimize risks when using the Supabase MCP server:

  • Don't connect to production: Use with development or staging projects only
  • Internal use only: Don't give access to customers or end users
  • Enable read-only mode when connecting to real data
  • Scope to specific projects to limit access
  • Use branching features to create safe development environments
  • Selectively enable tool groups to reduce the attack surface

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

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later