Skip to content
Back to search

supabase-mcp-server

Query MCP enables end-to-end management of Supabase via chat interface: read & write query executions, management API support, automatic migration versioning, access to logs and much more.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alexander-zuev--supabase-mcp-server/badge.svg)](/listings/alexander-zuev--supabase-mcp-server)

HTML

<a href="/listings/alexander-zuev--supabase-mcp-server"><img src="/api/listings/alexander-zuev--supabase-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

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:

# 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:

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.

> ๐Ÿ”‘ **Important**: Since v0.4 MCP server requires an API key which you can get for free at [thequery.dev](https://thequery.dev) to use this MCP server.

Environment Variables

The server uses the following environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | `SUPABASE_PROJECT_REF` | Yes | `127.0.0.1:54322` | Your Supabase project reference ID (or local host:port) | | `SUPABASE_DB_PASSWORD` | Yes | `postgres` | Your database password | | `SUPABASE_REGION` | Yes* | `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 | | `QUERY_API_KEY` | Yes | None | API key from thequery.dev (required for all operations) |

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

> ๐Ÿšจ **CRITICAL CONFIGURATION NOTE**: For remote Supabase projects, you MUST specify the correct region where your project is hosted using `SUPABASE_REGION`. If you encounter a "Tenant or user not found" error, this is almost certainly because your region setting doesn't match your project's actual region. You can find your project's region in the Supabase dashboard under Project Settings.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md ยท README ยท 573 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Query | MCP server for Supabase
  2. > ๐ŸŒ… More than 17k installs via pypi and close to 30k downloads on Smithery.ai โ€” in short, this was fun! ๐Ÿฅณ
  3. > Thanks to everyone who has been using this server for the past few months, and I hope it was useful for you.
  4. > Since Supabase has released their own [official MCP server](https://github.com/supabase-community/supabase-mcp),
  5. > I've decided to no longer actively maintain this one. The official MCP server is as feature-rich, and many more
  6. > features will be added in the future. Check it out!
  7. <p class="center-text">
  8. <strong>Query MCP is an open-source MCP server that lets your IDE safely run SQL, manage schema changes, call the Supabase Management API, and use Auth Admin SDK โ€” all with built-in safety controls.</strong>
  9. </p>
  10. <p class="center-text">
  11. <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>
  12. <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>
  13. <a href="https://codecov.io/gh/alexander-zuev/supabase-mcp-server"><img src="https://codecov.io/gh/alexander-zuev/supabase-mcp-server/branch/main/graph/badge.svg" alt="Code Coverage" /></a>
  14. <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>
  15. <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-package%20manager-blueviolet" alt="uv package manager" /></a>
  16. <a href="https://pepy.tech/project/supabase-mcp-server"><img src="https://static.pepy.tech/badge/supabase-mcp-server" alt="PyPI Downloads" /></a>
  17. <a href="https://smithery.ai/server/@alexander-zuev/supabase-mcp-server"><img src="https://smithery.ai/badge/@alexander-zuev/supabase-mcp-server" alt="Smithery.ai Downloads" /></a>
  18. <a href="https://modelcontextprotocol.io/introduction"><img src="https://img.shields.io/badge/MCP-Server-orange" alt="MCP Server" /></a>
  19. <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License" /></a>
  20. </p>
  21. ## Table of contents
  22. <p class="center-text">
  23. <a href="#getting-started">Getting started</a> โ€ข
  24. <a href="#feature-overview">Feature overview</a> โ€ข
  25. <a href="#troubleshooting">Troubleshooting</a> โ€ข
  26. <a href="#changelog">Changelog</a>
  27. </p>
  28. ## โœจ Key features
  29. - ๐Ÿ’ป Compatible with Cursor, Windsurf, Cline and other MCP clients supporting `stdio` protocol
  30. - ๐Ÿ” Control read-only and read-write modes of SQL query execution
  31. - ๐Ÿ” Runtime SQL query validation with risk level assessment
  32. - ๐Ÿ›ก๏ธ Three-tier safety system for SQL operations: safe, write, and destructive
  33. - ๐Ÿ”„ Robust transaction handling for both direct and pooled database connections
  34. - ๐Ÿ“ Automatic versioning of database schema changes
  35. - ๐Ÿ’ป Manage your Supabase projects with Supabase Management API
  36. - ๐Ÿง‘โ€๐Ÿ’ป Manage users with Supabase Auth Admin methods via Python SDK
  37. - ๐Ÿ”จ Pre-built tools to help Cursor & Windsurf work with MCP more effectively
  38. - ๐Ÿ“ฆ Dead-simple install & setup via package manager (uv, pipx, etc.)
  39. ## Getting Started
  40. ### Prerequisites
  41. Installing the server requires the following on your system:
  42. - Python 3.12+
  43. If you plan to install via `uv`, ensure it's [installed](https://docs.astral.sh/uv/getting-started/installation/#__tabbed_1_1).
  44. ### PostgreSQL Installation
  45. PostgreSQL installation is no longer required for the MCP server itself, as it now uses asyncpg which doesn't depend on PostgreSQL development libraries.
  46. However, you'll still need PostgreSQL if you're running a local Supabase instance:
  47. **MacOS**
  48. ```bash
  49. brew install postgresql@16
  50. ```
  51. **Windows**
  52. - Download and install PostgreSQL 16+ from https://www.postgresql.org/download/windows/
  53. - Ensure "PostgreSQL Server" and "Command Line Tools" are selected during installation
  54. ### Step 1. Installation
  55. Since v0.2.0 I introduced support for package installation. You can use your favorite Python package manager to install the server via:
  56. ```bash
  57. # if pipx is installed (recommended)
  58. pipx install supabase-mcp-server
  59. # if uv is installed
  60. uv pip install supabase-mcp-server
  61. ```
  62. `pipx` is recommended because it creates isolated environments for each package.
  63. You can also install the server manually by cloning the repository and running `pipx install -e .` from the root directory.
  64. #### Installing from source
  65. If you would like to install from source, for example for local development:
  66. ```bash
  67. uv venv
  68. # On Mac
  69. source .venv/bin/activate
  70. # On Windows
  71. .venv\Scripts\activate
  72. # Install package in editable mode
  73. uv pip install -e .
  74. ```
  75. #### Installing via Smithery.ai
  76. 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).
  77. ### Step 2. Configuration
  78. 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.
  79. > ๐Ÿ”‘ **Important**: Since v0.4 MCP server requires an API key which you can get for free at [thequery.dev](https://thequery.dev) to use this MCP server.
  80. #### Environment Variables
  81. The server uses the following environment variables:
  82. | Variable | Required | Default | Description |
  83. |----------|----------|---------|-------------|
  84. | `SUPABASE_PROJECT_REF` | Yes | `127.0.0.1:54322` | Your Supabase project reference ID (or local host:port) |
  85. | `SUPABASE_DB_PASSWORD` | Yes | `postgres` | Your database password |
  86. | `SUPABASE_REGION` | Yes* | `us-east-1` | AWS region where your Supabase project is hosted |
  87. | `SUPABASE_ACCESS_TOKEN` | No | None | Personal access token for Supabase Management API |
  88. | `SUPABASE_SERVICE_ROLE_KEY` | No | None | Service role key for Auth Admin SDK |
  89. | `QUERY_API_KEY` | Yes | None | API key from thequery.dev (required for all operations) |
  90. > **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`.
  91. > ๐Ÿšจ **CRITICAL CONFIGURATION NOTE**: For remote Supabase projects, you MUST specify the correct region where your project is hosted using `SUPABASE_REGION`. If you encounter a "Tenant or user not found" error, this is almost certainly because your region setting doesn't match your project's actual region. You can find your project's region in the Supabase dashboard under Project Settings.
  92. #### Connection Types
  93. ##### Database Connection
  94. - The server connects to your Supabase PostgreSQL database using the transaction pooler endpoint
  95. - Local development uses a direct connection to `127.0.0.1:54322`
  96. - Remote projects use the format: `postgresql://postgres.[project_ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres`
  97. > โš ๏ธ **Important**: Session pooling connections are not supported. The server exclusively uses transaction pooling for better compatibility with the MCP server architecture.
  98. ##### Management API Connection
  99. - Requires `SUPABASE_ACCESS_TOKEN` to be set
  100. - Connects to the Supabase Management API at `https://api.supabase.com`
  101. - Only works with remote Supabase projects (not local development)
  102. ##### Auth Admin SDK Connection
  103. - Requires `SUPABASE_SERVICE_ROLE_KEY` to be set
  104. - For local development, connects to `http://127.0.0.1:54321`
  105. - For remote projects, connects to `https://[project_ref].supabase.co`
  106. #### Configuration Methods
  107. The server looks for configuration in this order (highest to lowest priority):
  108. 1. **Environment Variables**: Values set directly in your environment
  109. 2. **Local `.env` File**: A `.env` file in your current working directory (only works when running from source)
  110. 3. **Global Config File**:
  111. - Windows: `%APPDATA%\supabase-mcp\.env`
  112. - macOS/Linux: `~/.config/supabase-mcp/.env`
  113. 4. **Default Settings**: Local development defaults (if no other config is found)
  114. > โš ๏ธ **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.
  115. #### Setting Up Configuration
  116. ##### Option 1: Client-Specific Configuration (Recommended)
  117. 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.
  118. ##### Option 2: Global Configuration
  119. Create a global `.env` configuration file that will be used for all MCP server instances:
  120. ```bash
  121. # Create config directory
  122. # On macOS/Linux
  123. mkdir -p ~/.config/supabase-mcp
  124. # On Windows (PowerShell)
  125. mkdir -Force "$env:APPDATA\supabase-mcp"
  126. # Create and edit .env file
  127. # On macOS/Linux
  128. nano ~/.config/supabase-mcp/.env
  129. # On Windows (PowerShell)
  130. notepad "$env:APPDATA\supabase-mcp\.env"
  131. ```
  132. Add your configuration values to the file:
  133. ```
  134. QUERY_API_KEY=your-api-key
  135. SUPABASE_PROJECT_REF=your-project-ref
  136. SUPABASE_DB_PASSWORD=your-db-password
  137. SUPABASE_REGION=us-east-1
  138. SUPABASE_ACCESS_TOKEN=your-access-token
  139. SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
  140. ```
  141. ##### Option 3: Project-Specific Configuration (Source Installation Only)
  142. 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.
  143. #### Finding Your Supabase Project Information
  144. - **Project Reference**: Found in your Supabase project URL: `https://supabase.com/dashboard/project/<project-ref>`
  145. - **Database Password**: Set during project creation or found in Project Settings โ†’ Database
  146. - **Access Token**: Generate at https://supabase.com/dashboard/account/tokens
  147. - **Service Role Key**: Found in Project Settings โ†’ API โ†’ Project API keys
  148. #### Supported Regions
  149. The server supports all Supabase regions:
  150. - `us-west-1` - West US (North California)
  151. - `us-east-1` - East US (North Virginia) - default
  152. - `us-east-2` - East US (Ohio)
  153. - `ca-central-1` - Canada (Central)
  154. - `eu-west-1` - West EU (Ireland)
  155. - `eu-west-2` - West Europe (London)
  156. - `eu-west-3` - West EU (Paris)
  157. - `eu-central-1` - Central EU (Frankfurt)
  158. - `eu-central-2` - Central Europe (Zurich)
  159. - `eu-north-1` - North EU (Stockholm)
  160. - `ap-south-1` - South Asia (Mumbai)
  161. - `ap-southeast-1` - Southeast Asia (Singapore)
  162. - `ap-northeast-1` - Northeast Asia (Tokyo)
  163. - `ap-northeast-2` - Northeast Asia (Seoul)
  164. - `ap-southeast-2` - Oceania (Sydney)
  165. - `sa-east-1` - South America (Sรฃo Paulo)
  166. #### Limitations
  167. - **No Self-Hosted Support**: The server only supports official Supabase.com hosted projects and local development
  168. - **No Connection String Support**: Custom connection strings are not supported
  169. - **No Session Pooling**: Only transaction pooling is supported for database connections
  170. - **API and SDK Features**: Management API and Auth Admin SDK features only work with remote Supabase projects, not local development
  171. ### Step 3. Usage
  172. In general, any MCP client that supports `stdio` protocol should work with this MCP server. This server was explicitly tested to work with:
  173. - Cursor
  174. - Windsurf
  175. - Cline
  176. - Claude Desktop
  177. Additionally, you can also use smithery.ai to install this server a number of clients, including the ones above.
  178. Follow the guides below to install this MCP server in your client.
  179. #### Cursor
  180. Go to Settings -> Features -> MCP Servers and add a new server with this configuration:
  181. ```bash
  182. # can be set to any name
  183. name: supabase
  184. type: command
  185. # if you installed with pipx
  186. command: supabase-mcp-server
  187. # if you installed with uv
  188. command: uv run supabase-mcp-server
  189. # if the above doesn't work, use the full path (recommended)
  190. command: /full/path/to/supabase-mcp-server # Find with 'which supabase-mcp-server' (macOS/Linux) or 'where supabase-mcp-server' (Windows)
  191. ```
  192. If configuration is correct, you should see a green dot indicator and the number of tools exposed by the server.
  193. ![How successful Cursor config looks like](https://github.com/user-attachments/assets/45df080a-8199-4aca-b59c-a84dc7fe2c09)
  194. #### Windsurf
  195. Go to Cascade -> Click on the hammer icon -> Configure -> Fill in the configuration:
  196. ```json
  197. {
  198. "mcpServers": {
  199. "supabase": {
  200. "command": "/Users/username/.local/bin/supabase-mcp-server", // update path
  201. "env": {
  202. "QUERY_API_KEY": "your-api-key", // Required - get your API key at thequery.dev
  203. "SUPABASE_PROJECT_REF": "your-project-ref",
  204. "SUPABASE_DB_PASSWORD": "your-db-password",
  205. "SUPABASE_REGION": "us-east-1", // optional, defaults to us-east-1
  206. "SUPABASE_ACCESS_TOKEN": "your-access-token", // optional, for management API
  207. "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key" // optional, for Auth Admin SDK
  208. }
  209. }
  210. }
  211. }
  212. ```
  213. If configuration is correct, you should see green dot indicator and clickable supabase server in the list of available servers.
  214. ![How successful Windsurf config looks like](https://github.com/user-attachments/assets/322b7423-8c71-410b-bcab-aff1b143faa4)
  215. #### Claude Desktop
  216. Claude Desktop also supports MCP servers through a JSON configuration. Follow these steps to set up the Supabase MCP server:
  217. 1. **Find the full path to the executable** (this step is critical):
  218. ```bash
  219. # On macOS/Linux
  220. which supabase-mcp-server
  221. # On Windows
  222. where supabase-mcp-server
  223. ```
  224. Copy the full path that is returned (e.g., `/Users/username/.local/bin/supabase-mcp-server`).
  225. 2. **Configure the MCP server** in Claude Desktop:
  226. - Open Claude Desktop
  227. - Go to Settings โ†’ Developer -> Edit Config MCP Servers
  228. - Add a new configuration with the following JSON:
  229. ```json
  230. {
  231. "mcpServers": {
  232. "supabase": {
  233. "command": "/full/path/to/supabase-mcp-server", // Replace with the actual path from step 1
  234. "env": {
  235. "QUERY_API_KEY": "your-api-key", // Required - get your API key at thequery.dev
  236. "SUPABASE_PROJECT_REF": "your-project-ref",
  237. "SUPABASE_DB_PASSWORD": "your-db-password",
  238. "SUPABASE_REGION": "us-east-1", // optional, defaults to us-east-1
  239. "SUPABASE_ACCESS_TOKEN": "your-access-token", // optional, for management API
  240. "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key" // optional, for Auth Admin SDK
  241. }
  242. }
  243. }
  244. }
  245. ```
  246. > โš ๏ธ **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.
  247. If configuration is correct, you should see the Supabase MCP server listed as available in Claude Desktop.
  248. ![How successful Windsurf config looks like](https://github.com/user-attachments/assets/500bcd40-6245-40a7-b23b-189827ed2923)
  249. #### Cline
  250. Cline also supports MCP servers through a similar JSON configuration. Follow these steps to set up the Supabase MCP server:
  251. 1. **Find the full path to the executable** (this step is critical):
  252. ```bash
  253. # On macOS/Linux
  254. which supabase-mcp-server
  255. # On Windows
  256. where supabase-mcp-server
  257. ```
  258. Copy the full path that is returned (e.g., `/Users/username/.local/bin/supabase-mcp-server`).
  259. 2. **Configure the MCP server** in Cline:
  260. - Open Cline in VS Code
  261. - Click on the "MCP Servers" tab in the Cline sidebar
  262. - Click "Configure MCP Servers"
  263. - This will open the `cline_mcp_settings.json` file
  264. - Add the following configuration:
  265. ```json
  266. {
  267. "mcpServers": {
  268. "supabase": {
  269. "command": "/full/path/to/supabase-mcp-server", // Replace with the actual path from step 1
  270. "env": {
  271. "QUERY_API_KEY": "your-api-key", // Required - get your API key at thequery.dev
  272. "SUPABASE_PROJECT_REF": "your-project-ref",
  273. "SUPABASE_DB_PASSWORD": "your-db-password",
  274. "SUPABASE_REGION": "us-east-1", // optional, defaults to us-east-1
  275. "SUPABASE_ACCESS_TOKEN": "your-access-token", // optional, for management API
  276. "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key" // optional, for Auth Admin SDK
  277. }
  278. }
  279. }
  280. }
  281. ```
  282. 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.
  283. ![How successful configuration in Cline looks like](https://github.com/user-attachments/assets/6c4446ad-7a58-44c6-bf12-6c82222bbe59)
  284. ### Troubleshooting
  285. Here are some tips & tricks that might help you:
  286. - **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.
  287. - **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.
  288. - **"No tools found" error** - If you see "Client closed - no tools available" in Cursor despite the package being installed:
  289. - Find the full path to the executable by running `which supabase-mcp-server` (macOS/Linux) or `where supabase-mcp-server` (Windows)
  290. - Use the full path in your MCP server configuration instead of just `supabase-mcp-server`
  291. - For example: `/Users/username/.local/bin/supabase-mcp-server` or `C:\Users\username\.local\bin\supabase-mcp-server.exe`
  292. - **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).
  293. - **Accessing logs** - The MCP server writes detailed logs to a file:
  294. - Log file location:
  295. - macOS/Linux: `~/.local/share/supabase-mcp/mcp_server.log`
  296. - Windows: `%USERPROFILE%\.local\share\supabase-mcp\mcp_server.log`
  297. - Logs include connection status, configuration details, and operation results
  298. - View logs using any text editor or terminal commands:
  299. ```bash
  300. # On macOS/Linux
  301. cat ~/.local/share/supabase-mcp/mcp_server.log
  302. # On Windows (PowerShell)
  303. Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"
  304. ```
  305. If you are stuck or any of the instructions above are incorrect, please raise an issue.
  306. ### MCP Inspector
  307. 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.
  308. > ๐Ÿ“ Running `supabase-mcp-inspector`, if installed from package, doesn't work properly - I will validate and fix in the coming release.
  309. ## Feature Overview
  310. ### Database query tools
  311. Since v0.3+ server provides comprehensive database management capabilities with built-in safety controls:
  312. - **SQL Query Execution**: Execute PostgreSQL queries with risk assessment
  313. - **Three-tier safety system**:
  314. - `safe`: Read-only operations (SELECT) - always allowed
  315. - `write`: Data modifications (INSERT, UPDATE, DELETE) - require unsafe mode
  316. - `destructive`: Schema changes (DROP, CREATE) - require unsafe mode + confirmation
  317. - **SQL Parsing and Validation**:
  318. - Uses PostgreSQL's parser (pglast) for accurate analysis and provides clear feedback on safety requirements
  319. - **Automatic Migration Versioning**:
  320. - Database-altering operations operations are automatically versioned
  321. - Generates descriptive names based on operation type and target
  322. - **Safety Controls**:
  323. - Default SAFE mode allows only read-only operations
  324. - All statements run in transaction mode via `asyncpg`
  325. - 2-step confirmation for high-risk operations
  326. - **Available Tools**:
  327. - `get_schemas`: Lists schemas with sizes and table counts
  328. - `get_tables`: Lists tables, foreign tables, and views with metadata
  329. - `get_table_schema`: Gets detailed table structure (columns, keys, relationships)
  330. - `execute_postgresql`: Executes SQL statements against your database
  331. - `confirm_destructive_operation`: Executes high-risk operations after confirmation
  332. - `retrieve_migrations`: Gets migrations with filtering and pagination options
  333. - `live_dangerously`: Toggles between safe and unsafe modes
  334. ### Management API tools
  335. Since v0.3.0 server provides secure access to the Supabase Management API with built-in safety controls:
  336. - **Available Tools**:
  337. - `send_management_api_request`: Sends arbitrary requests to Supabase Management API with auto-injection of project ref
  338. - `get_management_api_spec`: Gets the enriched API specification with safety information
  339. - Supports multiple query modes: by domain, by specific path/method, or all paths
  340. - Includes risk assessment information for each endpoint
  341. - Provides detailed parameter requirements and response formats
  342. - Helps LLMs understand the full capabilities of the Supabase Management API
  343. - `get_management_api_safety_rules`: Gets all safety rules with human-readable explanations
  344. - `live_dangerously`: Toggles between safe and unsafe operation modes
  345. - **Safety Controls**:
  346. - Uses the same safety manager as database operations for consistent risk management
  347. - Operations categorized by risk level:
  348. - `safe`: Read-only operations (GET) - always allowed
  349. - `unsafe`: State-changing operations (POST, PUT, PATCH, DELETE) - require unsafe mode
  350. - `blocked`: Destructive operations (delete project, etc.) - never allowed
  351. - Default safe mode prevents accidental state changes
  352. - Path-based pattern matching for precise safety rules
  353. **Note**: Management API tools only work with remote Supabase instances and are not compatible with local Supabase development setups.
  354. ### Auth Admin tools
  355. I was planning to add support for Python SDK methods to the MCP server. Upon consideration I decided to only add support for Auth admin methods as I often found myself manually creating test users which was prone to errors and time consuming. Now I can just ask Cursor to create a test user and it will be done seamlessly. Check out the full Auth Admin SDK method docs to know what it can do.
  356. Since v0.3.6 server supports direct access to Supabase Auth Admin methods via Python SDK:
  357. - Includes the following tools:
  358. - `get_auth_admin_methods_spec` to retrieve documentation for all available Auth Admin methods
  359. - `call_auth_admin_method` to directly invoke Auth Admin methods with proper parameter handling
  360. - Supported methods:
  361. - `get_user_by_id`: Retrieve a user by their ID
  362. - `list_users`: List all users with pagination
  363. - `create_user`: Create a new user
  364. - `delete_user`: Delete a user by their ID
  365. - `invite_user_by_email`: Send an invite link to a user's email
  366. - `generate_link`: Generate an email link for various authentication purposes
  367. - `update_user_by_id`: Update user attributes by ID
  368. - `delete_factor`: Delete a factor on a user (currently not implemented in SDK)
  369. #### Why use Auth Admin SDK instead of raw SQL queries?
  370. The Auth Admin SDK provides several key advantages over direct SQL manipulation:
  371. - **Functionality**: Enables operations not possible with SQL alone (invites, magic links, MFA)
  372. - **Accuracy**: More reliable then creating and executing raw SQL queries on auth schemas
  373. - **Simplicity**: Offers clear methods with proper validation and error handling
  374. - Response format:
  375. - All methods return structured Python objects instead of raw dictionaries
  376. - Object attributes can be accessed using dot notation (e.g., `user.id` instead of `user["id"]`)
  377. - Edge cases and limitations:
  378. - UUID validation: Many methods require valid UUID format for user IDs and will return specific validation errors
  379. - Email configuration: Methods like `invite_user_by_email` and `generate_link` require email sending to be configured in your Supabase project
  380. - Link types: When generating links, different link types have different requirements:
  381. - `signup` links don't require the user to exist
  382. - `magiclink` and `recovery` links require the user to already exist in the system
  383. - Error handling: The server provides detailed error messages from the Supabase API, which may differ from the dashboard interface
  384. - Method availability: Some methods like `delete_factor` are exposed in the API but not fully implemented in the SDK
  385. ### Logs & Analytics
  386. The server provides access to Supabase logs and analytics data, making it easier to monitor and troubleshoot your applications:
  387. - **Available Tool**: `retrieve_logs` - Access logs from any Supabase service
  388. - **Log Collections**:
  389. - `postgres`: Database server logs
  390. - `api_gateway`: API gateway requests
  391. - `auth`: Authentication events
  392. - `postgrest`: RESTful API service logs
  393. - `pooler`: Connection pooling logs
  394. - `storage`: Object storage operations
  395. - `realtime`: WebSocket subscription logs
  396. - `edge_functions`: Serverless function executions
  397. - `cron`: Scheduled job logs
  398. - `pgbouncer`: Connection pooler logs
  399. - **Features**: Filter by time, search text, apply field filters, or use custom SQL queries
  400. Simplifies debugging across your Supabase stack without switching between interfaces or writing complex queries.
  401. ### Automatic Versioning of Database Changes
  402. "With great power comes great responsibility." While `execute_postgresql` tool coupled with aptly named `live_dangerously` tool provide a powerful and simple way to manage your Supabase database, it also means that dropping a table or modifying one is one chat message away. In order to reduce the risk of irreversible changes, since v0.3.8 the server supports:
  403. - automatic creation of migration scripts for all write & destructive sql operations executed on the database
  404. - improved safety mode of query execution, in which all queries are categorized in:
  405. - `safe` type: always allowed. Includes all read-only ops.
  406. - `write`type: requires `write` mode to be enabled by the user.
  407. - `destructive` type: requires `write` mode to be enabled by the user AND a 2-step confirmation of query execution for clients that do not execute tools automatically.
  408. ### Universal Safety Mode
  409. Since v0.3.8 Safety Mode has been standardized across all services (database, API, SDK) using a universal safety manager. This provides consistent risk management and a unified interface for controlling safety settings across the entire MCP server.
  410. All operations (SQL queries, API requests, SDK methods) are categorized into risk levels:
  411. - `Low` risk: Read-only operations that don't modify data or structure (SELECT queries, GET API requests)
  412. - `Medium` risk: Write operations that modify data but not structure (INSERT/UPDATE/DELETE, most POST/PUT API requests)
  413. - `High` risk: Destructive operations that modify database structure or could cause data loss (DROP/TRUNCATE, DELETE API endpoints)
  414. - `Extreme` risk: Operations with severe consequences that are blocked entirely (deleting projects)
  415. Safety controls are applied based on risk level:
  416. - Low risk operations are always allowed
  417. - Medium risk operations require unsafe mode to be enabled
  418. - High risk operations require unsafe mode AND explicit confirmation
  419. - Extreme risk operations are never allowed
  420. #### How confirmation flow works
  421. Any high-risk operations (be it a postgresql or api request) will be blocked even in `unsafe` mode.
  422. ![Every high-risk operation is blocked](https://github.com/user-attachments/assets/c0df79c2-a879-4b1f-a39d-250f9965c36a)
  423. You will have to confirm and approve every high-risk operation explicitly in order for it to be executed.
  424. ![Explicit approval is always required](https://github.com/user-attachments/assets/5cd7a308-ec2a-414e-abe2-ff2f3836dd8b)
  425. ## Changelog
  426. - ๐Ÿ“ฆ Simplified installation via package manager - โœ… (v0.2.0)
  427. - ๐ŸŒŽ Support for different Supabase regions - โœ… (v0.2.2)
  428. - ๐ŸŽฎ Programmatic access to Supabase management API with safety controls - โœ… (v0.3.0)
  429. - ๐Ÿ‘ทโ€โ™‚๏ธ Read and read-write database SQL queries with safety controls - โœ… (v0.3.0)
  430. - ๐Ÿ”„ Robust transaction handling for both direct and pooled connections - โœ… (v0.3.2)
  431. - ๐Ÿ Support methods and objects available in native Python SDK - โœ… (v0.3.6)
  432. - ๐Ÿ” Stronger SQL query validation โœ… (v0.3.8)
  433. - ๐Ÿ“ Automatic versioning of database changes โœ… (v0.3.8)
  434. - ๐Ÿ“– Radically improved knowledge and tools of api spec โœ… (v0.3.8)
  435. - โœ๏ธ Improved consistency of migration-related tools for a more organized database vcs โœ… (v0.3.10)
  436. - ๐Ÿฅณ Query MCP is released (v0.4.0)
  437. For a more detailed roadmap, please see this [discussion](https://github.com/alexander-zuev/supabase-mcp-server/discussions/46) on GitHub.
  438. ## Star History
  439. [![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)
  440. ---
  441. Enjoy! โ˜บ๏ธ

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.