Supabase MCP server for AI agents

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