Supabase MCP server

Supabase MCP Server provides a secure interface for executing SQL queries, managing your database, accessing the Management API, and handling user authentication within your favorite MCP-enabled IDEs like Cursor, Windsurf, and Claude Desktop.

Installation

Prerequisites

• Python 3.12 or higher
• A Supabase project (local or remote)

Installing the Server

Choose one of these installation methods:

# Using pipx (recommended for isolation)
pipx install supabase-mcp-server

# Using uv
uv pip install supabase-mcp-server

Configuration

The MCP server needs configuration to connect to your Supabase resources. You have several options for providing this configuration.

Required Environment Variables

Critical Note: For remote Supabase projects, you MUST specify the correct region where your project is hosted using SUPABASE_REGION. Incorrect regions will cause connection errors.

Configuration Methods

The server checks these locations for configuration (in priority order):

1. Environment variables in your shell
2. Global config file:
   • Windows: %APPDATA%\supabase-mcp\.env
   • macOS/Linux: ~/.config/supabase-mcp/.env
3. Default local development settings

Setting Up Global Configuration

# Create config directory (macOS/Linux)
mkdir -p ~/.config/supabase-mcp

# Create config directory (Windows PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp"

# Edit the config file
nano ~/.config/supabase-mcp/.env  # macOS/Linux
notepad "$env:APPDATA\supabase-mcp\.env"  # Windows

Add your configuration values:

SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1
SUPABASE_ACCESS_TOKEN=your-access-token
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

Connecting with MCP Clients

Cursor

1. Go to Settings → Features → MCP Servers

2. Add a new server with this configuration:

   name: supabase
   type: command
   command: /full/path/to/supabase-mcp-server
   

   Find the full path with which supabase-mcp-server (macOS/Linux) or where supabase-mcp-server (Windows)

Windsurf

1. Go to Cascade → Click hammer icon → Configure
2. Add this configuration:

   {
       "mcpServers": {
         "supabase": {
           "command": "/full/path/to/supabase-mcp-server",
           "env": {
             "SUPABASE_PROJECT_REF": "your-project-ref",
             "SUPABASE_DB_PASSWORD": "your-db-password",
             "SUPABASE_REGION": "us-east-1",
             "SUPABASE_ACCESS_TOKEN": "your-access-token",
             "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
           }
         }
       }
   }
   

Claude Desktop

1. Go to Settings → Developer → Edit Config MCP Servers
2. Add this configuration:

   {
     "mcpServers": {
       "supabase": {
         "command": "/full/path/to/supabase-mcp-server",
         "env": {
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",
           "SUPABASE_ACCESS_TOKEN": "your-access-token",
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
         }
       }
     }
   }
   

Cline

1. Open Cline in VS Code
2. Click "MCP Servers" tab in sidebar → "Configure MCP Servers"
3. Add this configuration to the opened JSON file:

   {
     "mcpServers": {
       "supabase": {
         "command": "/full/path/to/supabase-mcp-server",
         "env": {
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",
           "SUPABASE_ACCESS_TOKEN": "your-access-token",
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
         }
       }
     }
   }
   

Key Features and Tools

Database Query Tools

• SQL Query Execution: Run PostgreSQL queries with built-in safety controls
  • execute_postgresql: Run SQL with automatic risk assessment
  • get_schemas: List schemas with sizes and table counts
  • get_tables: List tables, foreign tables, and views with metadata
  • get_table_schema: Get detailed table structure

Management API Tools

• API Access: Interact with Supabase Management API securely
  • send_management_api_request: Send requests to Management API
  • get_management_api_spec: Get documentation for available endpoints

Auth Admin Tools

• User Management: Manage Supabase users programmatically
  • call_auth_admin_method: Execute Auth Admin SDK methods
  • Supports user creation, deletion, updates, and more

Logs & Analytics

• Monitoring: Access logs from any Supabase service
  • retrieve_logs: Get logs from database, auth, API, storage, and more
  • Filter by time, search text, or use custom SQL queries

Safety Features

All operations are protected by a three-tier safety system:

• Safe Mode (default): Only read-only operations allowed
• Write Mode: Enable with live_dangerously for data modifications
• High-Risk Operations: Require explicit confirmation, even in write mode

Troubleshooting

If you encounter issues:

1. Verify Installation: Run supabase-mcp-server directly in terminal
2. Check Path: Use full path in client configuration (which supabase-mcp-server)
3. Review Logs: Check log file at:
   • macOS/Linux: ~/.local/share/supabase-mcp/mcp_server.log
   • Windows: %USERPROFILE%\.local\share\supabase-mcp\mcp_server.log
4. Confirm Region: Ensure you're using the correct SUPABASE_REGION value for remote projects

For more help, check GitHub issues or community support channels.

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.