| Name | supabase-mcp-server JSON |
| Version |
0.2.2
JSON |
| download |
| home_page | None |
| Summary | Unofficial MCP server for Supabase providing basic schema, table, and column management. |
| upload_time | 2025-02-20 12:40:08 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | None |
| keywords |
cursor
mcp
supabase
windsurf
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Supabase MCP Server
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/4a363bcd-7c15-47fa-a72a-d159916517f7" />
<source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/d255388e-cb1b-42ea-a7b2-0928f031e0df" />
<img alt="Supabase" src="https://github.com/user-attachments/assets/d255388e-cb1b-42ea-a7b2-0928f031e0df" height="40" />
</picture>
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/38db1bcd-50df-4a49-a106-1b5afd924cb2" />
<source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/82603097-07c9-42bb-9cbc-fb8f03560926" />
<img alt="MCP" src="https://github.com/user-attachments/assets/82603097-07c9-42bb-9cbc-fb8f03560926" height="40" />
</picture>
</p>
<p align="center">
<strong>Let Cursor & Windsurf interact with Supabase</strong>
</p>
[](https://star-history.com/#alexander-zuev/supabase-mcp-server&Date)
<p align="center">
<a href="https://pypi.org/project/supabase-mcp-server/"><img src="https://img.shields.io/pypi/v/supabase-mcp-server.svg" alt="PyPI version" /></a>
<a href="https://github.com/alexander-zuev/supabase-mcp-server/actions"><img src="https://github.com/alexander-zuev/supabase-mcp-server/workflows/CI/badge.svg" alt="CI Status" /></a>
<a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python 3.12+" /></a>
<a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-package%20manager-blueviolet" alt="uv package manager" /></a>
<a href="https://smithery.ai/server/@alexander-zuev/supabase-mcp"><img src="https://smithery.ai/badge/@alexander-zuev/supabase-mcp" alt="smithery badge" /></a>
<a href="https://modelcontextprotocol.io/introduction"><img src="https://img.shields.io/badge/MCP-Server-orange" alt="MCP Server" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License" /></a>
</p>
Unofficial feature-rich Supabase MCP server that enables Cursor and Windsurf to manage your database, execute SQL queries, and use every method and object in Python SDK.
## ✨ Key features
- 💻 Designed to work with Windsurf, Cursor, Cline and other MCP-compatible IDEs
- ✅ Pre-configured to work with both free and paid Supabase projects (direct and transaction pooling connection)
- 🔨 Pre-built database exploration tools with schema insights greatly improve LLM 'onboarding experience' into your db
- 🔐 Enforces read-only mode when executing SQL queries
- 🔍 Basic QoL features like query validation, retry logic for connection errors
- 📦 Installation via package manager (uv, pipx, etc.) or from source
## Prerequisites
- Python 3.12+
- PostgreSQL 16+
- uv package manager
### PostgreSQL Installation
> ⚠️ **Important**: PostgreSQL must be installed BEFORE installing project dependencies, as psycopg2 requires PostgreSQL development libraries during compilation.
**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
## MCP Server Installation
> ⚠️ **0.2.0 Breaking change**: Installation and execution methods have changed to support package distribution. The server now runs as a proper Python module instead of a direct script.
You can install Supabase MCP Server either using a package manager (recommended) or from source (just as in v0.1.0).
### Using Package Managers (Recommended)
Choose the installation method based on your needs:
```bash
# Using pipx (recommended for CLI tools)
pipx install supabase-mcp-server
# → Run with: supabase-mcp-server
# Using UV (if you prefer your current environment)
uv pip install supabase-mcp-server
# → Run with: uv run supabase-mcp-server
```
Why these package managers?
- `pipx`:
- Creates isolated environments for CLI tools
- Makes commands globally available as `supabase-mcp-server`
- Prevents dependency conflicts
- Best for end users who just want to use the tool
- `uv`:
- Installs in your current environment
- Faster installation and dependency resolution
- Requires `uv run` prefix to execute
- Better for development or if you're using uv for other packages
### Installing from Source
1. Clone the repository
```bash
git clone https://github.com/alexander-zuev/supabase-mcp-server.git
cd supabase-mcp-server
```
2. Create and activate virtual environment
```bash
# Create venv
uv venv
# Activate it
# On Mac/Linux
source .venv/bin/activate
# On Windows
.venv\Scripts\activate
```
3. Install in editable mode
```bash
uv pip install -e .
```
### Installing via Smithery
Please report any issues with Smithery, as I haven't tested it yet.
To install Supabase MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@alexander-zuev/supabase-mcp):
```bash
npx -y @smithery/cli install @alexander-zuev/supabase-mcp --client claude
```
## Running Supabase MCP Server
This MCP server was designed to be used with AI IDEs like Cursor and Windsurf and not tested with other clients. However, it should work with any MCP-compatible IDE as long as it uses stdio protocol.
You can run the server in several ways:
- as a package script (if you installed it using package manager)
- as a python module (if you installed it from source)
> 💡 **0.2.0 Breaking change**: Installation and execution methods have changed to support package distribution. The server now runs as a proper Python module instead of a direct script:
> - Old: `uv --directory /path/to/supabase-mcp-server run main.py`
> - New: `uv run supabase-mcp-server` (if installed via package manager)
> - New: `uv --directory /path/to/supabase-mcp-server run python -m supabase_mcp.main` (if installed from source)
### Running as a package script (if you installed it using package manager)
If you installed it using package manager, you can run the server with this command:
```bash
# Pipx
supabase-mcp-server
# UV
uv run supabase-mcp-server
```
#### Setup Cursor
> ⚠️ **Important**: Unlike Windsurf's defacto standard JSON configuration, Cursor team had a 'genius' idea to abstract away the underlying configuration into a barebones, poorly documented UI (took me several hours to figure out how to set it up) 😡. So in order to connect to a remote Supabase project, you need to set environment variables globally. I've provided a way to pick up .env file from a global config directory (`~/.config/supabase-mcp/.env` on macOS/Linux or `%APPDATA%\supabase-mcp\.env` on Windows).
1. Set up global config (recommended approach):
```bash
# Create config directory
# On macOS/Linux
mkdir -p ~/.config/supabase-mcp && cd ~/.config/supabase-mcp
# On Windows (in PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp" ; cd "$env:APPDATA\supabase-mcp"
# Create and open .env file
# On macOS/Linux
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1 # optional, defaults to us-east-1" > .env && open .
# On Windows (in PowerShell)
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1 # optional, defaults to us-east-1" > .env ; explorer .
```
2. Create a new MCP server in Cursor:
```
name: supabase
protocol: command
# if pipx (recommended)
command: supabase-mcp-server
# if uv
command: uv run supabase-mcp-server
```
3. Reload Cursor
If you encounter connection issues, try closing and reopening Cursor.
#### Setup Windsurf
> 💡 **Setting environment variables**: For Windsurf, it's recommended to set environment variables directly in the `mcp_config.json` as shown below.
1. Add / modify `mcp_config.json` file:
```json
{
"mcpServers": {
"supabase": {
"command": "/Users/your-username/.local/bin/supabase-mcp-server",
"env": {
"SUPABASE_PROJECT_REF": "your-project-ref",
"SUPABASE_DB_PASSWORD": "your-db-password",
"SUPABASE_REGION": "us-east-1" // optional, defaults to us-east-1
}
}
}
}
```
Don't forget to replace `your-username` with your actual username. You can find where it's located by running `which supabase-mcp-server` in terminal.
> 💡 **Finding Supabase MCP Server executable path**:
> - On macOS/Linux: Run `which supabase-mcp-server` in terminal
> - On Windows: Run `where supabase-mcp-server` in command prompt
> The output will show the full path to use in your configuration.
### Running as a python module (if you installed it from source)
If you installed from source or want to run the development version, use this command:
```bash
uv --directory /path/to/supabase-mcp-server run python -m supabase_mcp.main
```
#### Setup Cursor
1. Create a new MCP server
2. Add the following configuration:
```
name: supabase
protocol: command
command: uv --directory /path/to/supabase-mcp-server run python -m supabase_mcp.main
```
Replace `/path/to/supabase-mcp-server` with your actual repository path, for example:
```
command: uv --directory /Users/username/projects/supabase-mcp-server run python -m supabase_mcp.main
```
#### Setup Windsurf
1. Add / modify `mcp_config.json` file:
```json
{
"mcpServers": {
"supabase": {
"command": "/Users/az/.local/bin/uv",
"args": [
"--directory",
"/path/to/supabase-mcp-server",
"run",
"python",
"-m",
"supabase_mcp.main"
],
"env": {
"SUPABASE_PROJECT_REF": "your-project-ref",
"SUPABASE_DB_PASSWORD": "your-db-password",
"SUPABASE_REGION": "us-east-1" // optional, defaults to us-east-1
}
}
}
}
```
### Configuring connection to different Supabase projects
> 💡 **Tip**: Connection to local Supabase project is configured out of the box. You don't need to set environment variables.
To connect to a different Supabase project, you need to set environment variables:
- `SUPABASE_PROJECT_REF`
- `SUPABASE_DB_PASSWORD`
- `SUPABASE_REGION` (optional, defaults to `us-east-1`)
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)
The recommended way to set these variables depends on your IDE:
- **For Windsurf**: Set them directly in `mcp_config.json` (cleanest approach)
- **For Cursor**: Set them using global config directory (see [Setup Cursor](#setup-cursor))
- **For local development**: Use `.env` in the project root (when installed from source)
#### Local Supabase project
If no configuration is provided, the server defaults to local Supabase settings:
- Host: `127.0.0.1:54322`
- Password: `postgres`
This works out of the box with Supabase CLI's local development setup.
#### Remote Supabase project (staging / production)
##### When using Windsurf
Set the environment variables directly in your `mcp_config.json`:
```json
{
"mcpServers": {
"supabase": {
"command": "/Users/your-username/.local/bin/supabase-mcp-server",
"env": {
"SUPABASE_PROJECT_REF": "your-project-ref",
"SUPABASE_DB_PASSWORD": "your-db-password",
"SUPABASE_REGION": "us-east-1" // optional, defaults to us-east-1
}
}
}
}
```
> 💡 **Finding Supabase MCP Server executable path**:
> - On macOS/Linux: Run `which supabase-mcp-server` in terminal
> - On Windows: Run `where supabase-mcp-server` in command prompt
> The output will show the full path to use in your configuration.
##### When using Cursor
Create a global config file:
```bash
# Create config directory and navigate to it
# On macOS/Linux
mkdir -p ~/.config/supabase-mcp && cd ~/.config/supabase-mcp
# On Windows (in PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp" ; cd "$env:APPDATA\supabase-mcp"
# Create and open .env file
# On macOS/Linux
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1 # optional, defaults to us-east-1" > .env && open .
# On Windows (in PowerShell)
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1 # optional, defaults to us-east-1" > .env ; explorer .
```
Then in Cursor's MCP server configuration:
```
name: supabase
protocol: command
# if pipx (recommended)
command: supabase-mcp-server
# if uv
command: uv run supabase-mcp-server
```
> 💡 **Note**: Unlike Windsurf, Cursor requires configuration via global config file or environment variables. The global config approach is recommended for better maintainability.
##### Global config
3. **Global config** (Lowest precedence)
```bash
# Create in your home config directory for persistent access
mkdir -p ~/.config/supabase-mcp
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1 # optional, defaults to us-east-1" > ~/.config/supabase-mcp/.env
```
Perfect for developers who want to set up once and use across multiple projects.
##### When developing locally (installed from source)
Create `.env` file in the root of the cloned repository:
```bash
# In the supabase-mcp-server directory (project root)
echo "SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1 # optional, defaults to us-east-1" > .env
```
When running from source, it looks for `.env` in the project root directory (where you cloned the repository).
## How to troubleshoot common issues?
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.
- **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). The required variables are `SUPABASE_PROJECT_REF` and `SUPABASE_DB_PASSWORD`, with optional `SUPABASE_REGION` (defaults to `us-east-1`).
## Future improvements
- 📦 Simplified installation via package manager - ✅ (0.2.0)
- 🌎 Support for different Supabase regions - ✅ (0.2.2)
- 🐍 Support methods and objects available in native Python SDK
- 🎮 Programmatic access to Supabase management API (Support for creating edge functions, managing secrets (similar to Loveble integration)
- 🔍 Strong SQL query validation
Raw data
{
"_id": null,
"home_page": null,
"name": "supabase-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "cursor, mcp, supabase, windsurf",
"author": null,
"author_email": "Alexander Zuev <azuev@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/3c/71/b4cae4cd88cbbf403162ab90e07eac53671e798f1c592a641bf5d1134b82/supabase_mcp_server-0.2.2.tar.gz",
"platform": null,
"description": "# Supabase MCP Server\n\n<p align=\"center\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/user-attachments/assets/4a363bcd-7c15-47fa-a72a-d159916517f7\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/user-attachments/assets/d255388e-cb1b-42ea-a7b2-0928f031e0df\" />\n <img alt=\"Supabase\" src=\"https://github.com/user-attachments/assets/d255388e-cb1b-42ea-a7b2-0928f031e0df\" height=\"40\" />\n </picture>\n \n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/user-attachments/assets/38db1bcd-50df-4a49-a106-1b5afd924cb2\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/user-attachments/assets/82603097-07c9-42bb-9cbc-fb8f03560926\" />\n <img alt=\"MCP\" src=\"https://github.com/user-attachments/assets/82603097-07c9-42bb-9cbc-fb8f03560926\" height=\"40\" />\n </picture>\n</p>\n\n<p align=\"center\">\n <strong>Let Cursor & Windsurf interact with Supabase</strong>\n</p>\n\n[](https://star-history.com/#alexander-zuev/supabase-mcp-server&Date)\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/supabase-mcp-server/\"><img src=\"https://img.shields.io/pypi/v/supabase-mcp-server.svg\" alt=\"PyPI version\" /></a>\n <a href=\"https://github.com/alexander-zuev/supabase-mcp-server/actions\"><img src=\"https://github.com/alexander-zuev/supabase-mcp-server/workflows/CI/badge.svg\" alt=\"CI Status\" /></a>\n <a href=\"https://www.python.org/downloads/\"><img src=\"https://img.shields.io/badge/python-3.12%2B-blue.svg\" alt=\"Python 3.12+\" /></a>\n <a href=\"https://github.com/astral-sh/uv\"><img src=\"https://img.shields.io/badge/uv-package%20manager-blueviolet\" alt=\"uv package manager\" /></a>\n <a href=\"https://smithery.ai/server/@alexander-zuev/supabase-mcp\"><img src=\"https://smithery.ai/badge/@alexander-zuev/supabase-mcp\" alt=\"smithery badge\" /></a>\n <a href=\"https://modelcontextprotocol.io/introduction\"><img src=\"https://img.shields.io/badge/MCP-Server-orange\" alt=\"MCP Server\" /></a>\n <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-Apache%202.0-blue.svg\" alt=\"License\" /></a>\n</p>\n\n\n\nUnofficial feature-rich Supabase MCP server that enables Cursor and Windsurf to manage your database, execute SQL queries, and use every method and object in Python SDK.\n\n## \u2728 Key features\n- \ud83d\udcbb Designed to work with Windsurf, Cursor, Cline and other MCP-compatible IDEs\n- \u2705 Pre-configured to work with both free and paid Supabase projects (direct and transaction pooling connection)\n- \ud83d\udd28 Pre-built database exploration tools with schema insights greatly improve LLM 'onboarding experience' into your db\n- \ud83d\udd10 Enforces read-only mode when executing SQL queries\n- \ud83d\udd0d Basic QoL features like query validation, retry logic for connection errors\n- \ud83d\udce6 Installation via package manager (uv, pipx, etc.) or from source\n\n## Prerequisites\n- Python 3.12+\n- PostgreSQL 16+\n- uv package manager\n\n### PostgreSQL Installation\n> \u26a0\ufe0f **Important**: PostgreSQL must be installed BEFORE installing project dependencies, as psycopg2 requires PostgreSQL development libraries during compilation.\n\n**MacOS**\n```bash\nbrew install postgresql@16\n```\n\n**Windows**\n - Download and install PostgreSQL 16+ from https://www.postgresql.org/download/windows/\n - Ensure \"PostgreSQL Server\" and \"Command Line Tools\" are selected during installation\n\n## MCP Server Installation\n\n> \u26a0\ufe0f **0.2.0 Breaking change**: Installation and execution methods have changed to support package distribution. The server now runs as a proper Python module instead of a direct script.\n\nYou can install Supabase MCP Server either using a package manager (recommended) or from source (just as in v0.1.0).\n\n### Using Package Managers (Recommended)\n\nChoose the installation method based on your needs:\n\n```bash\n# Using pipx (recommended for CLI tools)\npipx install supabase-mcp-server\n# \u2192 Run with: supabase-mcp-server\n\n# Using UV (if you prefer your current environment)\nuv pip install supabase-mcp-server\n# \u2192 Run with: uv run supabase-mcp-server\n```\n\nWhy these package managers?\n- `pipx`:\n - Creates isolated environments for CLI tools\n - Makes commands globally available as `supabase-mcp-server`\n - Prevents dependency conflicts\n - Best for end users who just want to use the tool\n\n- `uv`:\n - Installs in your current environment\n - Faster installation and dependency resolution\n - Requires `uv run` prefix to execute\n - Better for development or if you're using uv for other packages\n\n### Installing from Source\n\n1. Clone the repository\n```bash\ngit clone https://github.com/alexander-zuev/supabase-mcp-server.git\ncd supabase-mcp-server\n```\n\n2. Create and activate virtual environment\n```bash\n# Create venv\nuv venv\n\n# Activate it\n# On Mac/Linux\nsource .venv/bin/activate\n# On Windows\n.venv\\Scripts\\activate\n```\n\n3. Install in editable mode\n```bash\nuv pip install -e .\n```\n\n### Installing via Smithery\n\nPlease report any issues with Smithery, as I haven't tested it yet.\n\nTo install Supabase MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@alexander-zuev/supabase-mcp):\n\n```bash\nnpx -y @smithery/cli install @alexander-zuev/supabase-mcp --client claude\n```\n\n\n## Running Supabase MCP Server\n\nThis MCP server was designed to be used with AI IDEs like Cursor and Windsurf and not tested with other clients. However, it should work with any MCP-compatible IDE as long as it uses stdio protocol.\n\nYou can run the server in several ways:\n- as a package script (if you installed it using package manager)\n- as a python module (if you installed it from source)\n\n> \ud83d\udca1 **0.2.0 Breaking change**: Installation and execution methods have changed to support package distribution. The server now runs as a proper Python module instead of a direct script:\n> - Old: `uv --directory /path/to/supabase-mcp-server run main.py`\n> - New: `uv run supabase-mcp-server` (if installed via package manager)\n> - New: `uv --directory /path/to/supabase-mcp-server run python -m supabase_mcp.main` (if installed from source)\n\n\n### Running as a package script (if you installed it using package manager)\n\nIf you installed it using package manager, you can run the server with this command:\n\n```bash\n# Pipx\nsupabase-mcp-server\n\n# UV\nuv run supabase-mcp-server\n```\n\n\n#### Setup Cursor\n\n> \u26a0\ufe0f **Important**: Unlike Windsurf's defacto standard JSON configuration, Cursor team had a 'genius' idea to abstract away the underlying configuration into a barebones, poorly documented UI (took me several hours to figure out how to set it up) \ud83d\ude21. So in order to connect to a remote Supabase project, you need to set environment variables globally. I've provided a way to pick up .env file from a global config directory (`~/.config/supabase-mcp/.env` on macOS/Linux or `%APPDATA%\\supabase-mcp\\.env` on Windows).\n\n1. Set up global config (recommended approach):\n```bash\n# Create config directory\n# On macOS/Linux\nmkdir -p ~/.config/supabase-mcp && cd ~/.config/supabase-mcp\n# On Windows (in PowerShell)\nmkdir -Force \"$env:APPDATA\\supabase-mcp\" ; cd \"$env:APPDATA\\supabase-mcp\"\n\n# Create and open .env file\n# On macOS/Linux\necho \"SUPABASE_PROJECT_REF=your-project-ref\nSUPABASE_DB_PASSWORD=your-db-password\nSUPABASE_REGION=us-east-1 # optional, defaults to us-east-1\" > .env && open .\n# On Windows (in PowerShell)\necho \"SUPABASE_PROJECT_REF=your-project-ref\nSUPABASE_DB_PASSWORD=your-db-password\nSUPABASE_REGION=us-east-1 # optional, defaults to us-east-1\" > .env ; explorer .\n```\n\n2. Create a new MCP server in Cursor:\n```\nname: supabase\nprotocol: command\n# if pipx (recommended)\ncommand: supabase-mcp-server\n# if uv\ncommand: uv run supabase-mcp-server\n```\n\n3. Reload Cursor\nIf you encounter connection issues, try closing and reopening Cursor.\n\n#### Setup Windsurf\n\n> \ud83d\udca1 **Setting environment variables**: For Windsurf, it's recommended to set environment variables directly in the `mcp_config.json` as shown below.\n\n\n1. Add / modify `mcp_config.json` file:\n```json\n{\n \"mcpServers\": {\n \"supabase\": {\n \"command\": \"/Users/your-username/.local/bin/supabase-mcp-server\",\n \"env\": {\n \"SUPABASE_PROJECT_REF\": \"your-project-ref\",\n \"SUPABASE_DB_PASSWORD\": \"your-db-password\",\n \"SUPABASE_REGION\": \"us-east-1\" // optional, defaults to us-east-1\n }\n }\n }\n}\n```\nDon't forget to replace `your-username` with your actual username. You can find where it's located by running `which supabase-mcp-server` in terminal.\n\n\n> \ud83d\udca1 **Finding Supabase MCP Server executable path**:\n> - On macOS/Linux: Run `which supabase-mcp-server` in terminal\n> - On Windows: Run `where supabase-mcp-server` in command prompt\n> The output will show the full path to use in your configuration.\n\n### Running as a python module (if you installed it from source)\n\nIf you installed from source or want to run the development version, use this command:\n\n```bash\nuv --directory /path/to/supabase-mcp-server run python -m supabase_mcp.main\n```\n\n#### Setup Cursor\n1. Create a new MCP server\n2. Add the following configuration:\n```\nname: supabase\nprotocol: command\ncommand: uv --directory /path/to/supabase-mcp-server run python -m supabase_mcp.main\n```\n\nReplace `/path/to/supabase-mcp-server` with your actual repository path, for example:\n```\ncommand: uv --directory /Users/username/projects/supabase-mcp-server run python -m supabase_mcp.main\n```\n\n#### Setup Windsurf\n1. Add / modify `mcp_config.json` file:\n```json\n{\n \"mcpServers\": {\n \"supabase\": {\n \"command\": \"/Users/az/.local/bin/uv\",\n \"args\": [\n \"--directory\",\n \"/path/to/supabase-mcp-server\",\n \"run\",\n \"python\",\n \"-m\",\n \"supabase_mcp.main\"\n ],\n \"env\": {\n \"SUPABASE_PROJECT_REF\": \"your-project-ref\",\n \"SUPABASE_DB_PASSWORD\": \"your-db-password\",\n \"SUPABASE_REGION\": \"us-east-1\" // optional, defaults to us-east-1\n }\n }\n }\n}\n```\n\n### Configuring connection to different Supabase projects\n\n> \ud83d\udca1 **Tip**: Connection to local Supabase project is configured out of the box. You don't need to set environment variables.\n\nTo connect to a different Supabase project, you need to set environment variables:\n- `SUPABASE_PROJECT_REF`\n- `SUPABASE_DB_PASSWORD`\n- `SUPABASE_REGION` (optional, defaults to `us-east-1`)\n\nThe server supports all Supabase regions:\n- `us-west-1` - West US (North California)\n- `us-east-1` - East US (North Virginia) - default\n- `us-east-2` - East US (Ohio)\n- `ca-central-1` - Canada (Central)\n- `eu-west-1` - West EU (Ireland)\n- `eu-west-2` - West Europe (London)\n- `eu-west-3` - West EU (Paris)\n- `eu-central-1` - Central EU (Frankfurt)\n- `eu-central-2` - Central Europe (Zurich)\n- `eu-north-1` - North EU (Stockholm)\n- `ap-south-1` - South Asia (Mumbai)\n- `ap-southeast-1` - Southeast Asia (Singapore)\n- `ap-northeast-1` - Northeast Asia (Tokyo)\n- `ap-northeast-2` - Northeast Asia (Seoul)\n- `ap-southeast-2` - Oceania (Sydney)\n- `sa-east-1` - South America (S\u00e3o Paulo)\n\nThe recommended way to set these variables depends on your IDE:\n- **For Windsurf**: Set them directly in `mcp_config.json` (cleanest approach)\n- **For Cursor**: Set them using global config directory (see [Setup Cursor](#setup-cursor))\n- **For local development**: Use `.env` in the project root (when installed from source)\n\n#### Local Supabase project\n\nIf no configuration is provided, the server defaults to local Supabase settings:\n- Host: `127.0.0.1:54322`\n- Password: `postgres`\n\nThis works out of the box with Supabase CLI's local development setup.\n\n#### Remote Supabase project (staging / production)\n\n##### When using Windsurf\nSet the environment variables directly in your `mcp_config.json`:\n```json\n{\n \"mcpServers\": {\n \"supabase\": {\n \"command\": \"/Users/your-username/.local/bin/supabase-mcp-server\",\n \"env\": {\n \"SUPABASE_PROJECT_REF\": \"your-project-ref\",\n \"SUPABASE_DB_PASSWORD\": \"your-db-password\",\n \"SUPABASE_REGION\": \"us-east-1\" // optional, defaults to us-east-1\n }\n }\n }\n}\n```\n\n> \ud83d\udca1 **Finding Supabase MCP Server executable path**:\n> - On macOS/Linux: Run `which supabase-mcp-server` in terminal\n> - On Windows: Run `where supabase-mcp-server` in command prompt\n> The output will show the full path to use in your configuration.\n\n\n##### When using Cursor\nCreate a global config file:\n```bash\n# Create config directory and navigate to it\n# On macOS/Linux\nmkdir -p ~/.config/supabase-mcp && cd ~/.config/supabase-mcp\n# On Windows (in PowerShell)\nmkdir -Force \"$env:APPDATA\\supabase-mcp\" ; cd \"$env:APPDATA\\supabase-mcp\"\n\n# Create and open .env file\n# On macOS/Linux\necho \"SUPABASE_PROJECT_REF=your-project-ref\nSUPABASE_DB_PASSWORD=your-db-password\nSUPABASE_REGION=us-east-1 # optional, defaults to us-east-1\" > .env && open .\n# On Windows (in PowerShell)\necho \"SUPABASE_PROJECT_REF=your-project-ref\nSUPABASE_DB_PASSWORD=your-db-password\nSUPABASE_REGION=us-east-1 # optional, defaults to us-east-1\" > .env ; explorer .\n```\n\nThen in Cursor's MCP server configuration:\n```\nname: supabase\nprotocol: command\n# if pipx (recommended)\ncommand: supabase-mcp-server\n# if uv\ncommand: uv run supabase-mcp-server\n```\n\n> \ud83d\udca1 **Note**: Unlike Windsurf, Cursor requires configuration via global config file or environment variables. The global config approach is recommended for better maintainability.\n\n##### Global config\n3. **Global config** (Lowest precedence)\n ```bash\n # Create in your home config directory for persistent access\n mkdir -p ~/.config/supabase-mcp\n echo \"SUPABASE_PROJECT_REF=your-project-ref\n SUPABASE_DB_PASSWORD=your-db-password\n SUPABASE_REGION=us-east-1 # optional, defaults to us-east-1\" > ~/.config/supabase-mcp/.env\n ```\n Perfect for developers who want to set up once and use across multiple projects.\n\n\n\n##### When developing locally (installed from source)\nCreate `.env` file in the root of the cloned repository:\n```bash\n# In the supabase-mcp-server directory (project root)\necho \"SUPABASE_PROJECT_REF=your-project-ref\nSUPABASE_DB_PASSWORD=your-db-password\nSUPABASE_REGION=us-east-1 # optional, defaults to us-east-1\" > .env\n```\nWhen running from source, it looks for `.env` in the project root directory (where you cloned the repository).\n\n\n\n## How to troubleshoot common issues?\n\nHere are some tips & tricks that might help you:\n- **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.\n- **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.\n- **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). The required variables are `SUPABASE_PROJECT_REF` and `SUPABASE_DB_PASSWORD`, with optional `SUPABASE_REGION` (defaults to `us-east-1`).\n\n\n## Future improvements\n\n- \ud83d\udce6 Simplified installation via package manager - \u2705 (0.2.0)\n- \ud83c\udf0e Support for different Supabase regions - \u2705 (0.2.2)\n- \ud83d\udc0d Support methods and objects available in native Python SDK\n- \ud83c\udfae Programmatic access to Supabase management API (Support for creating edge functions, managing secrets (similar to Loveble integration)\n- \ud83d\udd0d Strong SQL query validation\n",
"bugtrack_url": null,
"license": null,
"summary": "Unofficial MCP server for Supabase providing basic schema, table, and column management.",
"version": "0.2.2",
"project_urls": {
"Changelog": "https://github.com/alexander-zuev/supabase-mcp-server/blob/main/CHANGELOG.MD",
"Documentation": "https://github.com/alexander-zuev/supabase-mcp-server#readme",
"Homepage": "https://github.com/alexander-zuev/supabase-mcp-server",
"Repository": "https://github.com/alexander-zuev/supabase-mcp-server.git"
},
"split_keywords": [
"cursor",
" mcp",
" supabase",
" windsurf"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9fad73f5a83e4df8168f8231b1aa7288fc4f6b08ac3026e0afdbe8d55dfc127c",
"md5": "5de4b03575d2c5d5250391f375c17bd5",
"sha256": "a3aaa4d58c972a35ed3f33fd3d27593e2fd39ad5273bb1ad8976e702ceabd282"
},
"downloads": -1,
"filename": "supabase_mcp_server-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5de4b03575d2c5d5250391f375c17bd5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 18924,
"upload_time": "2025-02-20T12:40:03",
"upload_time_iso_8601": "2025-02-20T12:40:03.546402Z",
"url": "https://files.pythonhosted.org/packages/9f/ad/73f5a83e4df8168f8231b1aa7288fc4f6b08ac3026e0afdbe8d55dfc127c/supabase_mcp_server-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3c71b4cae4cd88cbbf403162ab90e07eac53671e798f1c592a641bf5d1134b82",
"md5": "77d350e708a44c28289df9b0b8f8e0df",
"sha256": "e2e2164f9e8dd278bf21baef2b83d1d6e78f48bb2581a0b5f8d6f675c1172b51"
},
"downloads": -1,
"filename": "supabase_mcp_server-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "77d350e708a44c28289df9b0b8f8e0df",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 55369,
"upload_time": "2025-02-20T12:40:08",
"upload_time_iso_8601": "2025-02-20T12:40:08.180989Z",
"url": "https://files.pythonhosted.org/packages/3c/71/b4cae4cd88cbbf403162ab90e07eac53671e798f1c592a641bf5d1134b82/supabase_mcp_server-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-20 12:40:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alexander-zuev",
"github_project": "supabase-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "supabase-mcp-server"
}
