diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index c06c55a..9bd7536 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -6,6 +6,10 @@ on: pull_request: branches: [ main ] + +env: + UV_VERSION: "0.6.1" # Pin uv version to avoid breaking changes + jobs: test: runs-on: ubuntu-latest @@ -21,26 +25,25 @@ jobs: python-version: "3.12" - name: Install uv - run: | - curl -LsSf https://astral.sh/uv/install.sh | sh - echo "$HOME/.cargo/bin" >> $GITHUB_PATH + uses: astral-sh/setup-uv@v5 + with: + version: ${{ env.UV_VERSION }} - name: Create venv and install dependencies run: | # Create venv and install dependencies uv venv source .venv/bin/activate - uv pip install -e . - uv add --dev pytest pytest-asyncio pytest-mock + uv sync --group dev --frozen - name: Run tests run: | source .venv/bin/activate pytest - - name: Test build + - name: Build distribution packages run: | - uv build + uv build --no-sources # Verify dist contains both wheel and tar.gz test -f dist/*.whl test -f dist/*.tar.gz diff --git a/.github/workflows/docs/release-checklist.md b/.github/workflows/docs/release-checklist.md index ae13535..5516256 100644 --- a/.github/workflows/docs/release-checklist.md +++ b/.github/workflows/docs/release-checklist.md @@ -1,5 +1,6 @@ # Release Checklist +Pre-release 1. Tests pass 2. CI passes 3. Build succeeds @@ -9,13 +10,19 @@ 7. Tag and release on GitHub 8. Release is published to PyPI -## v0.2.3 - 2025-02-22 +Post-release +- Clean install from PyPi works + + + +## v0.3.0 - 2025-02-22 1. Tests pass - [X] -2. CI passes +2. CI passes - [X] 3. Build succeeds - [X] -4. Clean install succeeds -5. Documentation is up to date -6. Changelog is up to date -7. Tag and release on GitHub -8. Release is published to PyPI +4. Clean install succeeds - [X] +5. Documentation is up to date - [X] +6. Changelog is up to date - [X] +7. Tag and release on GitHub - [X] +8. Release is published to PyPI - [X] +9. Clean install from PyPI works - [X] diff --git a/.github/workflows/publish.yaml b/.github/workflows/publish.yaml index e8b1d17..c676cda 100644 --- a/.github/workflows/publish.yaml +++ b/.github/workflows/publish.yaml @@ -2,37 +2,76 @@ name: Publish to PyPI on: release: - types: [created] + types: [published] + branches: [main] # Only trigger for releases from main + +env: + UV_VERSION: "0.6.0" # Pin uv version to avoid breaking changes jobs: - publish: + build-and-publish: runs-on: ubuntu-latest - environment: release + environment: + name: pypi + url: https://test.pypi.org/project/supabase-mcp-server/ # TODO: Change to pypi.org after testing permissions: - id-token: write # mandatory for trusted publishing + id-token: write # Required for trusted publishing + contents: read steps: - uses: actions/checkout@v4 + with: + fetch-depth: 0 # Required for proper version detection + + - name: Install uv + uses: astral-sh/setup-uv@v5 + with: + version: ${{ env.UV_VERSION }} - - name: Set up Python 3.12 + - name: Set up Python uses: actions/setup-python@v5 with: python-version: "3.12" - - name: Install uv - run: | - curl -LsSf https://astral.sh/uv/install.sh | sh - echo "$HOME/.cargo/bin" >> $GITHUB_PATH - - name: Build package + run: uv build --no-sources + + - name: Verify package installation and entry points + env: + SUPABASE_PROJECT_REF: ${{ secrets.SUPABASE_PROJECT_REF }} + SUPABASE_DB_PASSWORD: ${{ secrets.SUPABASE_DB_PASSWORD }} run: | - uv venv - source .venv/bin/activate - uv pip install -e . - uv build + # Create a new venv for testing + uv venv --name test-venv + source test-venv/bin/activate + + # Install the built wheel + uv pip install dist/*.whl + + echo "Testing supabase-mcp-server entry point..." + # Run with --help to test basic functionality without needing actual connection + if ! uv run supabase-mcp-server --help; then + echo "❌ supabase-mcp-server --help failed" + exit 1 + fi + echo "✅ supabase-mcp-server --help succeeded" + + echo "Testing supabase-mcp-inspector entry point..." + if ! uv run supabase-mcp-inspector --help; then + echo "❌ supabase-mcp-inspector --help failed" + exit 1 + fi + echo "✅ supabase-mcp-inspector --help succeeded" + + # Test actual connection if credentials are available + echo "Testing actual connection with supabase-mcp-inspector..." + if ! timeout 30s uv run supabase-mcp-inspector; then + echo "❌ supabase-mcp-inspector connection test failed" + exit 1 + fi + echo "✅ supabase-mcp-inspector connection test succeeded" - name: Publish to PyPI - run: | - source .venv/bin/activate - uv pip install --upgrade build twine - uv publish + uses: pypa/gh-action-pypi-publish@release/v1 + with: + repository-url: https://test.pypi.org/legacy/ # TODO: Change to pypi.org after testing diff --git a/README.md b/README.md index 20828e2..c288925 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@

- Let Cursor & Windsurf interact with Supabase autonomously + Let Cursor & Windsurf manage your Supabase and run SQL queries. Autonomously. In a safe way.

[![Star History Chart](https://api.star-history.com/svg?repos=alexander-zuev/supabase-mcp-server&type=Date)](https://star-history.com/#alexander-zuev/supabase-mcp-server&Date) @@ -31,8 +31,16 @@

+A feature-rich MCP server that enables Cursor and Windsurf 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. -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. +## Table of contents +

+ Key features • + Getting started • + Feature guides • + Troubleshooting • + Roadmap +

## ✨ Key features - 💻 Compatible with Cursor, Windsurf, Cline and other MCP clients supporting `stdio` protocol @@ -41,10 +49,14 @@ Unofficial feature-rich Supabase MCP server that enables Cursor and Windsurf to - 🔨 Pre-built tools to help Cursor & Windsurf work with MCP more effectively - 📦 Dead-simple install & setup via package manager (uv, pipx, etc.) -## Prerequisites +## Getting Started Guide + +### Prerequisites +Installing the server requires the following on your system: - Python 3.12+ -- PostgreSQL 16+ -- uv package manager +- PostgresSQL 16+ + +If you plan to install via `uv`, ensure it's [installed](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_1). ### PostgreSQL Installation > ⚠️ **Important**: PostgreSQL must be installed BEFORE installing project dependencies, as psycopg2 requires PostgreSQL development libraries during compilation. @@ -58,66 +70,37 @@ brew install postgresql@16 - 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. +### Step 1. MCP Server Installation -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: +Since v0.2.0 I introduced support for package installation. You can use your favorite Python package manager to install the server via: ```bash -# Using pipx (recommended for CLI tools) +# if pipx is installed (recommended) pipx install supabase-mcp-server -# → Run with: supabase-mcp-server -# Using UV (if you prefer your current environment) +# if uv is installed 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 +`pipx` is recommended because it creates isolated environments for each package. -- `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 +You can also install the server manually by cloning the repository and running `pipx` install -editable . from the root directory. -### Installing from Source - -1. Clone the repository -```bash -git clone https://github.com/alexander-zuev/supabase-mcp-server.git -cd supabase-mcp-server -``` +> ⚠️ If you run into psycopg2 compilation issues, you might be missing PostgreSQL development packages. See above. -2. Create and activate virtual environment +#### Installing from source +If you would like to install from source, for example for local development: ```bash -# Create venv uv venv - -# Activate it -# On Mac/Linux +# On Mac source .venv/bin/activate # On Windows .venv\Scripts\activate -``` - -3. Install in editable mode -```bash +# Install package in editable mode uv pip install -e . ``` -### Installing via Smithery - +#### Installing via Smithery.ai 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): @@ -126,331 +109,227 @@ To install Supabase MCP Server for Claude Desktop automatically via [Smithery](h npx -y @smithery/cli install @alexander-zuev/supabase-mcp --client claude ``` +### Step 2. Configuration -## Running Supabase MCP Server +After installing the package, you'll need to configure your database connection settings. The server supports both local and remote Supabase instances. -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. +#### Local Supabase instance (Default) + Server is pre-configured to connect to the local Supabase instance using default settings: +- `Host`: 127.0.0.1:54322 +- `Password`: postgres -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) +>💡 As long as you didn't modify the default settings and you want to connect to the local instance, you don't need to set environment variables. -> 💡 **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) +#### Remote Supabase instance +For remote Supabase projects, you need to configure: +- `SUPABASE_PROJECT_REF` - Your project reference (found in project URL) +- `SUPABASE_DB_PASSWORD` - Your database password +- `SUPABASE_REGION` - (Optional) Defaults to `us-east-1` +- `SUPABASE_ACCESS_TOKEN` - (Optional) For Management API access +You can get your SUPABASE_PROJECT_REF from your project's dashboard URL: +- `https://supabase.com/dashboard/project/` -### Running as a package script (if you installed it using package manager) +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) + +Method of MCP configuration differs between Cursor and Windsurf. Read the relevant section to understand how to configure connection. -If you installed it using package manager, you can run the server with this command: +##### Cursor +Cursor does not currently support environment variable configuration via the MCP server UI. As a workaround, this server picks up a global .env file automatically. Cursor is expected to introduce .json config in v0.46, and this guide will be updated accordingly. +For now, create an `.env` file in a global config folder by running the following commands: ```bash -# Pipx -supabase-mcp-server +# Create config directory and navigate to it +# On macOS/Linux +mkdir -p ~/.config/supabase-mcp +cd ~/.config/supabase-mcp -# UV -uv run supabase-mcp-server +# On Windows (in PowerShell) +mkdir -Force "$env:APPDATA\supabase-mcp" +cd "$env:APPDATA\supabase-mcp" ``` +This creates the necessary config folder where your environment file will be stored. - -#### 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 +# Create and edit .env file # 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" +nano ~/.config/supabase-mcp/.env -# 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 . +# On Windows (PowerShell) +notepad "$env:APPDATA\supabase-mcp\.env" ``` -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 +This will open the .env file. Once the file is open, copy & paste the following: +```bash +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 ``` -3. Reload Cursor -If you encounter connection issues, try closing and reopening Cursor. - -#### Setup Windsurf +Verify the file exists - you should see the values you have just set: +```bash +# On macOS/Linux +cat ~/.config/supabase-mcp/.env -> 💡 **Setting environment variables**: For Windsurf, it's recommended to set environment variables directly in the `mcp_config.json` as shown below. +# On Windows (PowerShell) +Get-Content "$env:APPDATA\supabase-mcp\.env" +``` +You can find global config file: + - Windows: `%APPDATA%/supabase-mcp/.env` + - macOS/Linux: `~/.config/supabase-mcp/.env` -1. Add / modify `mcp_config.json` file: +##### Windsurf +Windsurf supports de facto standard .json format for MCP Servers configuration. You can configure the server in mcp_config.json file: ```json { "mcpServers": { "supabase": { - "command": "/Users/your-username/.local/bin/supabase-mcp-server", + "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_REGION": "us-east-1", // optional, defaults to us-east-1 + "SUPABASE_ACCESS_TOKEN": "your-access-token" // optional, for management API } } } } ``` -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 the server path**: +> - macOS/Linux: Run `which supabase-mcp-server` +> - Windows: Run `where supabase-mcp-server` -> 💡 **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. +#### Configuration Precedence +The server looks for configuration in this order: +1. Environment variables (highest priority) +2. Local `.env` file in current directory +3. Global config file: + - Windows: `%APPDATA%/supabase-mcp/.env` + - macOS/Linux: `~/.config/supabase-mcp/.env` +4. Default settings (local development) -### Running as a python module (if you installed it from source) +### Step 3. Running MCP Server in Cursor/Windsurf -If you installed from source or want to run the development version, use this command: +In general, any MCP client that supports `stdio` protocol should work with this MCP server (Cline, for example) but I haven't tested it with anything except Cursor/Windsurf. +#### Cursor +Go to Settings -> Features -> MCP Servers and add a new server with this configuration: ```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: -``` +# can be set to any name 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 - } - } - } -} +type: command +# if you installed with pipx +command: supabase-mcp-server +# if you installed with uv +command: uv run supabase-mcp-server ``` -### 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. +If configuration is correct, you should see a green dot indicator and the number of tools exposed by the server. +![How successful Cursor config looks like](https://github.com/user-attachments/assets/45df080a-8199-4aca-b59c-a84dc7fe2c09) -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`: +#### Windsurf +Go to Cascade -> Click on the hammer icon -> Configure -> Fill in the configuration: ```json { "mcpServers": { "supabase": { - "command": "/Users/your-username/.local/bin/supabase-mcp-server", + "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_REGION": "us-east-1", // optional, defaults to us-east-1 + "SUPABASE_ACCESS_TOKEN": "your-access-token" // optional, for management API } } } } ``` +If configuration is correct, you should see green dot indicator and clickable supabase server in the list of available servers. -> 💡 **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 -``` +![How successful Windsurf config looks like](https://github.com/user-attachments/assets/322b7423-8c71-410b-bcab-aff1b143faa4) -> 💡 **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? +### 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. -- **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`). - -## Feature overview +- **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). -### Supabase Connection Configuration +If you are stuck or any of the instructions above are incorrect, please raise an issue on GitHub. -Configuration of the connection to the Supabase project is done via environment variables. - - Supports all 16 Supabase regions - - Can be set in `mcp_config.json`, `.env` file or globally in `~/.config/supabase-mcp/.env` - - For local development, the server defaults to local Supabase settings: - - Host: `127.0.0.1:54322` - - Password: `postgres` - - For remote development, you need to set the environment variables directly in `mcp_config.json` or in `.env` file. - - `SUPABASE_PROJECT_REF` - your project ref (e.g. `project-ref`) - - `SUPABASE_DB_PASSWORD` - your database password - - `SUPABASE_REGION` - optional, defaults to `us-east-1` +## Feature Guides -### SQL query execution +### Database query tools As of v0.3, the server supports both read-only and read-write SQL queries. - - Supported modes: - - `read-only` - only read-only queries are allowed (default mode) - - `read-write` - all SQL operations are allowed when explicitly enabled - - Safety features: - - Starts in read-only mode by default - - Requires explicit mode switch for write operations - - Automatically resets to read-only mode after write operations - - Uses transactions to ensure clean state in tests +Available database tools: +- `get_db_schemas` - Lists all database schemas with their sizes and table counts +- `get_tables` - Lists all tables in a schema with their sizes, row counts, and metadata +- `get_table_schema` - Gets detailed table structure including columns, keys, and relationships +- `execute_sql_query` - Executes raw SQL queries with validation + +- Supported modes: + - `read-only` - only read-only queries are allowed (default mode) + - `read-write` - all SQL operations are allowed when explicitly enabled +- Safety features: + - Starts in read-only mode by default + - Requires explicit mode switch for write operations + - Automatically resets to read-only mode after write operations + - Uses transactions to ensure clean state in tests - SQL query validation [TODO] -### Supabase Management API +### Management API tools Introduced in v0.2.3, the server supports sending arbitrary requests to Supabase Management API with auto-injection of project ref and safety mode control: - Includes the following tools: - - `send_management_api_request` to send arbitrary requests to Supabase Management API, with auto-injection of project ref and safety mode control. + - `send_management_api_request` to send arbitrary requests to Supabase Management API, with auto-injection of project ref and safety mode control - `get_management_api_spec` to get the enriched API specification with safety information - `get_management_api_safety_rules` to get all safety rules including blocked and unsafe operations with human-readable explanations - - `live_dangerously` to switch to yolo mode + - `live_dangerously` to switch between safe and unsafe modes - Safety features: - Divides API methods into `safe`, `unsafe` and `blocked` categories based on the risk of the operation - - Allows to switch between safe and yolo modes dynamically + - Allows to switch between safe and unsafe modes dynamically - Blocked operations (delete project, delete database) are not allowed regardless of the mode -## Support of Python SDK methods -Future versions will include support for the following Python SDK methods +## Roadmap -## Connect to Supabase logs +- 📦 Simplified installation via package manager - ✅ (v0.2.0) +- 🌎 Support for different Supabase regions - ✅ (v0.2.2) +- 🎮 Programmatic access to Supabase management API with safety controls - ✅ (v0.3.0) +- 👷‍♂️ Read and read-write database SQL queries with safety controls - ✅ (v0.3.0) +- 🐍 Support methods and objects available in native Python SDK +- 🔍 Strong SQL query validation +- 📝 Connect to db logs to help debug errors -Future versions will include a tool to connect to Supabase logs to help debug errors. +### Support of Python SDK methods +I'm planning to add support for Auth methods from Python SDK as it would allow Cursor to create test users for me, which might be handy. -## Future improvements +### Connect to Supabase logs -- 📦 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 -- 👷‍♂️ Safe running of non read-only SQL queries -- 🎮 Programmatic access to Supabase management API -- 🔍 Strong SQL query validation -- 📝 Connect to db logs to help debug errors +I'm planning to research, if it's possible to connect to Supabase db logs which might be useful for debugging (if not already supported.) + + +--- + +Enjoy! ☺️ diff --git a/supabase_mcp/main.py b/supabase_mcp/main.py index 83df75f..3016516 100644 --- a/supabase_mcp/main.py +++ b/supabase_mcp/main.py @@ -139,8 +139,7 @@ async def live_dangerously(service: Literal["api", "database"], enable: bool = F @mcp.tool( description=""" -Get the complete Management API specification enriched with safety metadata. -Each operation includes safety level (safe/unsafe/blocked) and reasoning. +Get the latests complete Management API specification. Use this to understand available operations and their requirements. """ )