# Supabase Mcp Server

> MCP server from Niell007/supabase-mcp-server.

- **Type:** MCP server
- **Install:** `agentstack add mcp-niell007-supabase-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Niell007](https://agentstack.voostack.com/s/niell007)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [Niell007](https://github.com/Niell007)
- **Source:** https://github.com/Niell007/supabase-mcp-server

## Install

```sh
agentstack add mcp-niell007-supabase-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Supabase MCP Server

  
    
    
    
  
    
  
    
    
    
  

  Enable your favorite IDE to safely execute SQL queries, manage your database end-to-end, access Management API, and handle user authentication with built-in safety controls.

[](https://star-history.com/#alexander-zuev/supabase-mcp-server&Date)

  
  
  
  
  
  
  
  
  

A feature-rich MCP server that enables any MCP clients (Cursor, Windsurf, Claude Desktop, Cline and others) to safely interact with Supabase databases. It provides tools for database management, SQL query execution, and Supabase Management API access with built-in safety controls.

## Table of contents

  Getting started •
  Feature overview •
  Troubleshooting •
  Changelog

## ✨ Key features
- 💻 Compatible with Cursor, Windsurf, Cline and other MCP clients supporting `stdio` protocol
- 🔐 Control read-only and read-write modes of SQL query execution
- 🔍 Runtime SQL query validation with risk level assessment
- 🛡️ Three-tier safety system for SQL operations: safe, write, and destructive
- 🔄 Robust transaction handling for both direct and pooled database connections
- 📝 Automatic versioning of database schema changes
- 💻 Manage your Supabase projects with Supabase Management API
- 🧑‍💻 Manage users with Supabase Auth Admin methods via Python SDK
- 🔨 Pre-built tools to help Cursor & Windsurf work with MCP more effectively
- 📦 Dead-simple install & setup via package manager (uv, pipx, etc.)

## Getting Started

### Prerequisites
Installing the server requires the following on your system:
- Python 3.12+

If you plan to install via `uv`, ensure it's [installed](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_1).

### PostgreSQL Installation
PostgreSQL installation is no longer required for the MCP server itself, as it now uses asyncpg which doesn't depend on PostgreSQL development libraries.

However, you'll still need PostgreSQL if you're running a local Supabase instance:

**MacOS**
```bash
brew install postgresql@16
```

**Windows**
  - Download and install PostgreSQL 16+ from https://www.postgresql.org/download/windows/
  - Ensure "PostgreSQL Server" and "Command Line Tools" are selected during installation

### Step 1. Installation

Since v0.2.0 I introduced support for package installation. You can use your favorite Python package manager to install the server via:

```bash
# if pipx is installed (recommended)
pipx install supabase-mcp-server

# if uv is installed
uv pip install supabase-mcp-server
```

`pipx` is recommended because it creates isolated environments for each package.

You can also install the server manually by cloning the repository and running `pipx install -e .` from the root directory.

#### Installing from source
If you would like to install from source, for example for local development:
```bash
uv venv
# On Mac
source .venv/bin/activate
# On Windows
.venv\Scripts\activate
# Install package in editable mode
uv pip install -e .
```

#### Installing via Smithery.ai

You can find the full instructions on how to use Smithery.ai to connect to this MCP server [here](https://smithery.ai/server/@alexander-zuev/supabase-mcp-server).

### Step 2. Configuration

The Supabase MCP server requires configuration to connect to your Supabase database, access the Management API, and use the Auth Admin SDK. This section explains all available configuration options and how to set them up.

#### Environment Variables

The server uses the following environment variables:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `SUPABASE_PROJECT_REF` | No | `127.0.0.1:54322` | Your Supabase project reference ID (or local host:port) |
| `SUPABASE_DB_PASSWORD` | No | `postgres` | Your database password |
| `SUPABASE_REGION` | No | `us-east-1` | AWS region where your Supabase project is hosted |
| `SUPABASE_ACCESS_TOKEN` | No | None | Personal access token for Supabase Management API |
| `SUPABASE_SERVICE_ROLE_KEY` | No | None | Service role key for Auth Admin SDK |

> **Note**: The default values are configured for local Supabase development. For remote Supabase projects, you must provide your own values for `SUPABASE_PROJECT_REF` and `SUPABASE_DB_PASSWORD`.

#### Connection Types

##### Database Connection
- The server connects to your Supabase PostgreSQL database using the transaction pooler endpoint
- Local development uses a direct connection to `127.0.0.1:54322`
- Remote projects use the format: `postgresql://postgres.[project_ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres`

> ⚠️ **Important**: Session pooling connections are not supported. The server exclusively uses transaction pooling for better compatibility with the MCP server architecture.

##### Management API Connection
- Requires `SUPABASE_ACCESS_TOKEN` to be set
- Connects to the Supabase Management API at `https://api.supabase.com`
- Only works with remote Supabase projects (not local development)

##### Auth Admin SDK Connection
- Requires `SUPABASE_SERVICE_ROLE_KEY` to be set
- For local development, connects to `http://127.0.0.1:54321`
- For remote projects, connects to `https://[project_ref].supabase.co`

#### Configuration Methods

The server looks for configuration in this order (highest to lowest priority):

1. **Environment Variables**: Values set directly in your environment
2. **Local `.env` File**: A `.env` file in your current working directory (only works when running from source)
3. **Global Config File**:
   - Windows: `%APPDATA%\supabase-mcp\.env`
   - macOS/Linux: `~/.config/supabase-mcp/.env`
4. **Default Settings**: Local development defaults (if no other config is found)

> ⚠️ **Important**: When using the package installed via pipx or uv, local `.env` files in your project directory are **not** detected. You must use either environment variables or the global config file.

#### Setting Up Configuration

##### Option 1: Client-Specific Configuration (Recommended)

Set environment variables directly in your MCP client configuration (see client-specific setup instructions in Step 3). Most MCP clients support this approach, which keeps your configuration with your client settings.

##### Option 2: Global Configuration

Create a global `.env` configuration file that will be used for all MCP server instances:

```bash
# Create config directory
# On macOS/Linux
mkdir -p ~/.config/supabase-mcp
# On Windows (PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp"

# Create and edit .env file
# On macOS/Linux
nano ~/.config/supabase-mcp/.env
# On Windows (PowerShell)
notepad "$env:APPDATA\supabase-mcp\.env"
```

Add your configuration values to the file:

```
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
```

##### Option 3: Project-Specific Configuration (Source Installation Only)

If you're running the server from source (not via package), you can create a `.env` file in your project directory with the same format as above.

#### Finding Your Supabase Project Information

- **Project Reference**: Found in your Supabase project URL: `https://supabase.com/dashboard/project/`
- **Database Password**: Set during project creation or found in Project Settings → Database
- **Access Token**: Generate at https://supabase.com/dashboard/account/tokens
- **Service Role Key**: Found in Project Settings → API → Project API keys

#### Supported Regions

The server supports all Supabase regions:

- `us-west-1` - West US (North California)
- `us-east-1` - East US (North Virginia) - default
- `us-east-2` - East US (Ohio)
- `ca-central-1` - Canada (Central)
- `eu-west-1` - West EU (Ireland)
- `eu-west-2` - West Europe (London)
- `eu-west-3` - West EU (Paris)
- `eu-central-1` - Central EU (Frankfurt)
- `eu-central-2` - Central Europe (Zurich)
- `eu-north-1` - North EU (Stockholm)
- `ap-south-1` - South Asia (Mumbai)
- `ap-southeast-1` - Southeast Asia (Singapore)
- `ap-northeast-1` - Northeast Asia (Tokyo)
- `ap-northeast-2` - Northeast Asia (Seoul)
- `ap-southeast-2` - Oceania (Sydney)
- `sa-east-1` - South America (São Paulo)

#### Limitations

- **No Self-Hosted Support**: The server only supports official Supabase.com hosted projects and local development
- **No Connection String Support**: Custom connection strings are not supported
- **No Session Pooling**: Only transaction pooling is supported for database connections
- **API and SDK Features**: Management API and Auth Admin SDK features only work with remote Supabase projects, not local development

### Step 3. Usage

In general, any MCP client that supports `stdio` protocol should work with this MCP server. This server was explicitly tested to work with:
- Cursor
- Windsurf
- Cline
- Claude Desktop

Additionally, you can also use smithery.ai to install this server a number of clients, including the ones above.

Follow the guides below to install this MCP server in your client.

#### Cursor
Go to Settings -> Features -> MCP Servers and add a new server with this configuration:
```bash
# can be set to any name
name: supabase
type: command
# if you installed with pipx
command: supabase-mcp-server
# if you installed with uv
command: uv run supabase-mcp-server
# if the above doesn't work, use the full path (recommended)
command: /full/path/to/supabase-mcp-server  # Find with 'which supabase-mcp-server' (macOS/Linux) or 'where supabase-mcp-server' (Windows)
```

If configuration is correct, you should see a green dot indicator and the number of tools exposed by the server.

#### Windsurf
Go to Cascade -> Click on the hammer icon -> Configure -> Fill in the configuration:
```json
{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // update path
        "env": {
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
          "SUPABASE_ACCESS_TOKEN": "your-access-token",  // optional, for management API
          "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // optional, for Auth Admin SDK
        }
      }
    }
}
```
If configuration is correct, you should see green dot indicator and clickable supabase server in the list of available servers.

#### Claude Desktop
Claude Desktop also supports MCP servers through a JSON configuration. Follow these steps to set up the Supabase MCP server:

1. **Find the full path to the executable** (this step is critical):
   ```bash
   # On macOS/Linux
   which supabase-mcp-server

   # On Windows
   where supabase-mcp-server
   ```
   Copy the full path that is returned (e.g., `/Users/username/.local/bin/supabase-mcp-server`).

2. **Configure the MCP server** in Claude Desktop:
   - Open Claude Desktop
   - Go to Settings → Developer -> Edit Config MCP Servers
   - Add a new configuration with the following JSON:

   ```json
   {
     "mcpServers": {
       "supabase": {
         "command": "/full/path/to/supabase-mcp-server",  // Replace with the actual path from step 1
         "env": {
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
           "SUPABASE_ACCESS_TOKEN": "your-access-token",  // optional, for management API
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // optional, for Auth Admin SDK
         }
       }
     }
   }
   ```

> ⚠️ **Important**: Unlike Windsurf and Cursor, Claude Desktop requires the **full absolute path** to the executable. Using just the command name (`supabase-mcp-server`) will result in a "spawn ENOENT" error.

If configuration is correct, you should see the Supabase MCP server listed as available in Claude Desktop.

#### Cline
Cline also supports MCP servers through a similar JSON configuration. Follow these steps to set up the Supabase MCP server:

1. **Find the full path to the executable** (this step is critical):
   ```bash
   # On macOS/Linux
   which supabase-mcp-server

   # On Windows
   where supabase-mcp-server
   ```
   Copy the full path that is returned (e.g., `/Users/username/.local/bin/supabase-mcp-server`).

2. **Configure the MCP server** in Cline:
   - Open Cline in VS Code
   - Click on the "MCP Servers" tab in the Cline sidebar
   - Click "Configure MCP Servers"
   - This will open the `cline_mcp_settings.json` file
   - Add the following configuration:

   ```json
   {
     "mcpServers": {
       "supabase": {
         "command": "/full/path/to/supabase-mcp-server",  // Replace with the actual path from step 1
         "env": {
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
           "SUPABASE_ACCESS_TOKEN": "your-access-token",  // optional, for management API
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // optional, for Auth Admin SDK
         }
       }
     }
   }
   ```

If configuration is correct, you should see a green indicator next to the Supabase MCP server in the Cline MCP Servers list, and a message confirming "supabase MCP server connected" at the bottom of the panel.

### Troubleshooting

Here are some tips & tricks that might help you:
- **Debug installation** - run `supabase-mcp-server` directly from the terminal to see if it works. If it doesn't, there might be an issue with the installation.
- **MCP Server configuration** - if the above step works, it means the server is installed and configured correctly. As long as you provided the right command, IDE should be able to connect. Make sure to provide the right path to the server executable.
- **"No tools found" error** - If you see "Client closed - no tools available" in Cursor despite the package being installed:
  - Find the full path to the executable by running `which supabase-mcp-server` (macOS/Linux) or `where supabase-mcp-server` (Windows)
  - Use the full path in your MCP server configuration instead of just `supabase-mcp-server`
  - For example: `/Users/username/.local/bin/supabase-mcp-server` or `C:\Users\username\.local\bin\supabase-mcp-server.exe`
- **Environment variables** - to connect to the right database, make sure you either set env variables in `mcp_config.json` or in `.env` file placed in a global config directory (`~/.config/supabase-mcp/.env` on macOS/Linux or `%APPDATA%\supabase-mcp\.env` on Windows).
- **Accessing logs** - The MCP server writes detailed logs to a file:
  - Log file location:
    - macOS/Linux: `~/.local/share/supabase-mcp/mcp_server.log`
    - Windows: `%USERPROFILE%\.local\share\supabase-mcp\mcp_server.log`
  - Logs include connection status, configuration details, and operation results
  - View logs using any text editor or terminal commands:
    ```bash
    # On macOS/Linux
    cat ~/.local/share/supabase-mcp/mcp_server.log

    # On Windows (PowerShell)
    Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"
    ```

If you are stuck or any of the instructions above are incorrect, please raise an issue.

### MCP Inspector
A super useful tool to help debug MCP server issues is MCP Inspector. If you installed from source, you can run `supabase-mcp-inspector` from the project repo and it will run the inspector instance. Coupled with logs this will give you complete overview over what's happening in the server.
> 📝 Running `supabase-mcp-inspector`, if installed from package, doesn't work properly - I will validate and fix in the coming release.

## Feature Overview

### Database query tools

Since v0.3+ server provides comprehensive database management capabilities with built-in safety controls:

- **SQL Query Execution**: Execute PostgreSQL queries with risk assessment
  -

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Niell007](https://github.com/Niell007)
- **Source:** [Niell007/supabase-mcp-server](https://github.com/Niell007/supabase-mcp-server)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-niell007-supabase-mcp-server
- Seller: https://agentstack.voostack.com/s/niell007
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.