alexanderzuev/supabase-mcp-server

Query | Supabase 的 MCP server

> 🌅 通过 pypi 安装超过 17k 次，在 Smithery.ai 上下载近 30k 次 —— 总之，这段经历很有趣！🥳
> 感谢过去几个月使用此 server 的每一个人，希望它对你们有所帮助。
> 既然 Supabase 已经发布了他们的 official MCP server，
> 我决定不再积极维护这个版本。官方 MCP server 同样功能丰富，且未来会增加更多功能。快去看看吧！

<p class="center-text">
<strong>Query MCP 是一个开源的 MCP server，让你的 IDE 能够安全地运行 SQL、管理 schema 变更、调用 Supabase Management API 并使用 Auth Admin SDK —— 所有这些都内置了安全控制。</strong>
</p><p class="center-text">
<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://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>
<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://pepy.tech/project/supabase-mcp-server"><img src="https://static.pepy.tech/badge/supabase-mcp-server" alt="PyPI Downloads" /></a>
<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>
<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>

目录<p class="center-text">

✨ 核心特性

• 💻 兼容 Cursor, Windsurf, Cline 以及其他支持 stdio 协议的 MCP 客户端

• 🔐 控制 SQL 查询执行的只读和读写模式

• 🔍 运行时 SQL 查询验证及风险等级评估

• 🛡️ SQL 操作的三级安全体系：safe, write 和 destructive

• 🔄 针对直接连接和池化数据库连接的鲁棒事务处理

• 📝 数据库 schema 变更的自动版本控制

• 💻 通过 Supabase Management API 管理您的 Supabase 项目

• 🧑‍💻 通过 Python SDK 使用 Supabase Auth Admin 方法管理用户

• 🔨 内置工具帮助 Cursor & Windsurf 更高效地使用 MCP

• 📦 通过包管理器（uv, pipx 等）实现极简安装与配置

快速入门

前置条件

• Python 3.12+

如果您计划通过 uv 安装，请确保已安装。

PostgreSQL 安装

但如果您运行本地 Supabase 实例，仍然需要 PostgreSQL：

MacOS

brew install postgresql@16

Step 1. Installation

自 v0.2.0 起，我引入了对包安装的支持。你可以使用你喜欢的 Python 包管理器通过以下方式安装 server：

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

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

您也可以通过克隆仓库并在根目录下运行 pipx install -e . 来手动安装服务器。

#### 从源码安装
如果您想从源码安装（例如为了进行本地开发）：

uv venv
On Mac

source .venv/bin/activate
On Windows

.venv\Scripts\activate
Install package in editable mode

uv pip install -e .

您可以在此处找到关于如何使用 Smithery.ai 连接到此 MCP server 的完整指南。

步骤 2. 配置

Supabase MCP server 需要进行配置才能连接到您的 Supabase 数据库、访问 Management API 并使用 Auth Admin SDK。本节将详细说明所有可用的配置选项及其设置方法。

> 🔑 重要提示：自 v0.4 起，MCP server 要求提供 API key 才能使用，您可以从 thequery.dev 免费获取。

#### 环境变量

该 server 使用以下环境变量：

| 变量 | 必填 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| SUPABASE_PROJECT_REF | 是 | 127.0.0.1:54322 | 您的 Supabase 项目引用 ID（或本地 host:port） |
| SUPABASE_DB_PASSWORD | 是 | postgres | 您的数据库密码 |
| SUPABASE_REGION | 是* | us-east-1 | 托管 Supabase 项目的 AWS 区域 |
| SUPABASE_ACCESS_TOKEN | 否 | 无 | Supabase Management API 的个人访问令牌 |
| SUPABASE_SERVICE_ROLE_KEY | 否 | 无 | Auth Admin SDK 的服务角色密钥 |
| QUERY_API_KEY | 是 | 无 | 来自 thequery.dev 的 API key（所有操作均需提供） |> 注意：默认值是为本地 Supabase 开发配置的。对于远程 Supabase 项目，你必须为 SUPABASE_PROJECT_REF 和 SUPABASE_DB_PASSWORD 提供自己的值。

> 🚨 关键配置注意：对于远程 Supabase 项目，你必须使用 SUPABASE_REGION 指定项目托管的正确区域。如果你遇到 "Tenant or user not found" 错误，这几乎肯定是因为你的区域设置与项目的实际区域不匹配。你可以在 Supabase 控制面板的 Project Settings 中找到项目的区域。

#### 连接类型

##### 数据库连接

• 服务器通过 transaction pooler 端点连接到你的 Supabase PostgreSQL 数据库

• 本地开发使用对 127.0.0.1:54322 的直接连接

• 远程项目使用格式：postgresql://postgres.[project_ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

> ⚠️ 重要：不支持 session pooling 连接。为了更好地兼容 MCP server 架构，服务器专门使用 transaction pooling。

##### 管理 API 连接

• 需要设置 SUPABASE_ACCESS_TOKEN

• 连接到 https://api.supabase.com 的 Supabase Management API

• 仅适用于远程 Supabase 项目（不适用于本地开发）##### Auth Admin SDK 连接

• 需要设置 SUPABASE_SERVICE_ROLE_KEY

• 本地开发时，连接至 http://127.0.0.1:54321

• 远程项目时，连接至 https://[project_ref].supabase.co

#### 配置方法

服务器按以下顺序查找配置（优先级从高到低）：

1. 环境变量：直接在环境中设置的值
2. 本地 .env 文件：当前工作目录下的 .env 文件（仅在从源码运行时有效）
3. 全局配置文件：
- Windows: %APPDATA%\supabase-mcp\.env
- macOS/Linux: ~/.config/supabase-mcp/.env
4. 默认设置：本地开发默认值（若未找到其他配置）

> ⚠️ 重要：当使用通过 pipx 或 uv 安装的包时，项目目录下的本地 .env 文件不会被检测到。你必须使用环境变量或全局配置文件。

#### 设置配置

##### 选项 1：客户端特定配置（推荐）

直接在 MCP 客户端配置中设置环境变量（参见步骤 3 中的客户端特定设置指南）。大多数 MCP 客户端支持此方法，可将配置与客户端设置保持一致。

##### 选项 2：全局配置

创建一个全局 .env 配置文件，该文件将用于所有 MCP 服务器实例：

# Create config directory
On macOS/Linux

mkdir -p ~/.config/supabase-mcp
On Windows (PowerShell)

mkdir -Force "$env:APPDATA\supabase-mcp"

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

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

如果你是从源码运行服务器（而非通过包安装），可以在项目目录下创建一个与上述格式相同的 .env 文件。

#### 查找你的 Supabase 项目信息

• Project Reference：在你的 Supabase 项目 URL 中可以找到：https://supabase.com/dashboard/project/<project-ref>

• Database Password：在创建项目时设置，或在 Project Settings → Database 中查找

• Access Token：在 https://supabase.com/dashboard/account/tokens 生成

• Service Role Key：在 Project Settings → API → Project API keys 中查找

#### 支持的区域

服务器支持所有 Supabase 区域：

• us-west-1 - 美国西部 (北加州)

• us-east-1 - 美国东部 (北弗吉尼亚) - 默认

• us-east-2 - 美国东部 (俄亥俄)

• ca-central-1 - 加拿大 (中部)

• eu-west-1 - 欧盟西部 (爱尔兰)

• eu-west-2 - 西欧 (伦敦)

• eu-west-3 - 欧盟西部 (巴黎)

• eu-central-1 - 欧盟中部 (法兰克福)

• eu-central-2 - 中欧 (苏黎世)

• eu-north-1 - 欧盟北部 (斯德哥尔摩)

• ap-south-1 - 南亚 (孟买)

• ap-southeast-1 - 东南亚 (新加坡)

• ap-northeast-1 - 东北亚 (东京)

• ap-northeast-2 - 东北亚 (首尔)

• ap-southeast-2 - 大洋洲 (悉尼)

• sa-east-1 - 南美洲 (圣保罗)

#### 限制条件- 不支持自托管：服务器仅支持官方 Supabase.com 托管项目和本地开发

• 不支持连接字符串：不支持自定义 connection strings

• 不支持会话池 (Session Pooling)：数据库连接仅支持事务池 (transaction pooling)

• API 和 SDK 功能：Management API 和 Auth Admin SDK 功能仅适用于远程 Supabase 项目，不支持本地开发

步骤 3. 使用方法

通常情况下，任何支持 stdio 协议的 MCP 客户端都应能与此 MCP 服务器协同工作。该服务器已明确测试支持：

• Cursor

• Windsurf

• Cline

• Claude Desktop

此外，您还可以使用 smithery.ai 将此服务器安装到包括上述在内的多个客户端中。

请参考以下指南在您的客户端中安装此 MCP 服务器。

#### Cursor
前往 Settings -> Features -> MCP Servers，并使用以下配置添加新服务器：

# can be set to any name
name: supabase
type: command
if you installed with pipx

command: supabase-mcp-server
if you installed with uv

command: uv run supabase-mcp-server
if the above doesn't work, use the full path (recommended)

command: /full/path/to/supabase-mcp-server  # Find with 'which supabase-mcp-server' (macOS/Linux) or 'where supabase-mcp-server' (Windows)

#### Windsurf
前往 Cascade -> 点击锤子图标 -> Configure -> 填写配置：

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // update path
        "env": {
          "QUERY_API_KEY": "your-api-key",  // Required - get your API key at thequery.dev
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
          "SUPABASE_ACCESS_TOKEN": "your-access-token",  // optional, for management API
          "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // optional, for Auth Admin SDK
        }
      }
    }
}

!How successful Windsurf config looks like

#### Claude Desktop
Claude Desktop 同样通过 JSON 配置支持 MCP 服务器。请按照以下步骤设置 Supabase MCP 服务器：

1. 找到可执行文件的完整路径（此步骤至关重要）：

# On macOS/Linux
   which supabase-mcp-server

# On Windows
   where supabase-mcp-server

2. 在 Claude Desktop 中配置 MCP server：
- 打开 Claude Desktop
- 前往 Settings → Developer -> Edit Config MCP Servers
- 添加以下 JSON 新配置：

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

如果配置正确，你应该能在 Claude Desktop 中看到 Supabase MCP server 已列为可用。

!How successful Windsurf config looks like

#### Cline
Cline 同样通过类似的 JSON 配置支持 MCP servers。请按照以下步骤设置 Supabase MCP server：

1. 查找可执行文件的完整路径（此步骤至关重要）：

# On macOS/Linux
   which supabase-mcp-server

# On Windows
   where supabase-mcp-server

2. 在 Cline 中配置 MCP server：
- 在 VS Code 中打开 Cline
- 点击 Cline 侧边栏的 "MCP Servers" 标签页
- 点击 "Configure MCP Servers"
- 这将打开 cline_mcp_settings.json 文件
- 添加以下配置：

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

!How successful configuration in Cline looks like

Troubleshooting以下是一些可能对你有帮助的技巧与建议：

• 调试安装 - 直接在终端运行 supabase-mcp-server 以检查其是否正常工作。如果无法运行，可能是安装出现了问题。

• MCP Server 配置 - 如果上述步骤成功，说明服务器已正确安装和配置。只要提供了正确的命令，IDE 应该能够连接。请确保提供了服务器可执行文件的正确路径。

• “No tools found” 错误 - 如果在安装了包之后，Cursor 中仍显示 “Client closed - no tools available”：

• 环境变量 - 为了连接到正确的数据库，请确保你在 mcp_config.json 中设置了环境变量，或者在全局配置目录的 .env 文件中设置（macOS/Linux 为 ~/.config/supabase-mcp/.env，Windows 为 %APPDATA%\supabase-mcp\.env）。

• 访问日志 - MCP server 会将详细日志写入文件：

# On macOS/Linux
    cat ~/.local/share/supabase-mcp/mcp_server.log
# On Windows (PowerShell)
    Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"

MCP Inspector

Feature Overview

Database query tools

自 v0.3+ 起，server 提供了具有内置安全控制的全面数据库管理能力：

• SQL Query Execution：执行带有风险评估的 PostgreSQL 查询

• SQL Parsing and Validation：

• Automatic Migration Versioning：

• 可用工具:

Management API 工具

自 v0.3.0 起，服务器提供带有内置安全控制的 Supabase Management API 安全访问：- 可用工具:
- send_management_api_request: 向 Supabase Management API 发送任意请求，并自动注入 project ref
- get_management_api_spec: 获取包含安全信息的增强版 API 规范
- 支持多种查询模式：按 domain、按特定 path/method 或所有 path
- 包含每个 endpoint 的风险评估信息
- 提供详细的参数要求和响应格式
- 帮助 LLM 理解 Supabase Management API 的完整能力
- get_management_api_safety_rules: 获取所有带有易读解释的安全规则
- live_dangerously: 在安全模式和非安全操作模式之间切换

• 安全控制:

注意: Management API 工具仅适用于远程 Supabase 实例，不兼容本地 Supabase 开发环境。

Auth Admin 工具我原计划为 MCP server 添加对 Python SDK 方法的支持。经过考虑，我决定仅添加对 Auth admin 方法的支持，因为我经常发现手动创建测试用户既容易出错又耗时。现在我只需要求 Cursor 创建测试用户，即可无缝完成。请查阅完整的 Auth Admin SDK 方法文档以了解其功能。

自 v0.3.6 起，server 支持通过 Python SDK 直接访问 Supabase Auth Admin 方法：
- 包含以下 tools：
- get_auth_admin_methods_spec：用于检索所有可用 Auth Admin 方法的文档
- call_auth_admin_method：用于直接调用 Auth Admin 方法并处理相关参数
- 支持的方法：
- get_user_by_id：通过 ID 获取用户
- list_users：分页列出所有用户
- create_user：创建新用户
- delete_user：通过 ID 删除用户
- invite_user_by_email：向用户邮箱发送邀请链接
- generate_link：为各种身份验证目的生成电子邮件链接
- update_user_by_id：通过 ID 更新用户属性
- delete_factor：删除用户的 factor（目前 SDK 中尚未实现）

#### 为什么使用 Auth Admin SDK 而不是原始 SQL 查询？Auth Admin SDK 相比直接进行 SQL 操作具有几个关键优势：

• 功能性：实现了仅靠 SQL 无法完成的操作（邀请、magic links、MFA）

• 准确性：比在 auth schemas 上创建并执行原始 SQL 查询更可靠

• 简洁性：提供具有适当验证和错误处理的清晰方法

- 响应格式：
- 所有方法返回结构化的 Python 对象而非原始字典
- 可以使用点号表示法访问对象属性（例如 user.id 而非 user["id"]）
- 边界情况与限制：
- UUID 验证：许多方法要求用户 ID 必须为有效的 UUID 格式，否则将返回特定的验证错误
- 邮件配置：invite_user_by_email 和 generate_link 等方法要求在 Supabase 项目中配置邮件发送
- 链接类型：生成链接时，不同链接类型的要求不同：
- signup 链接不需要用户已存在
- magiclink 和 recovery 链接要求用户必须已存在于系统中
- 错误处理：服务器提供来自 Supabase API 的详细错误消息，这可能与 dashboard 界面有所不同
- 方法可用性：某些方法（如 delete_factor）在 API 中已公开，但在 SDK 中尚未完全实现

Logs & Analytics

服务器提供了对 Supabase logs 和 analytics 数据的访问，使监控和排查应用程序问题变得更加容易：- 可用工具: retrieve_logs - 访问任何 Supabase 服务的日志

• 日志集合:

• 功能: 支持按时间过滤、文本搜索、应用字段过滤或使用自定义 SQL 查询

简化了整个 Supabase 技术栈的调试过程，无需在不同界面间切换或编写复杂的查询。

数据库变更的自动版本控制“能力越大，责任越大。”虽然 execute_postgresql 工具配合 aptly named 的 live_dangerously 工具提供了一种强大且简单的方式来管理你的 Supabase 数据库，但这也意味着删除或修改表仅需一条聊天消息。为了降低不可逆变更的风险，自 v0.3.8 起，服务器支持：

• 为所有在数据库上执行的写操作和破坏性 sql 操作自动创建 migration 脚本

• 改进的查询执行安全模式，其中所有查询被分为：

通用安全模式

• Low 风险：不修改数据或结构的只读操作（SELECT queries, GET API requests）

• Medium 风险：修改数据但不修改结构的写入操作（INSERT/UPDATE/DELETE, 大多数 POST/PUT API requests）

• High 风险：修改数据库结构或可能导致数据丢失的破坏性操作（DROP/TRUNCATE, DELETE API endpoints）

• Extreme 风险：后果严重且被完全拦截的操作（删除项目）

安全控制根据风险等级应用：

• Low 风险操作始终允许

• Medium 风险操作需要启用 unsafe mode

• High 风险操作需要启用 unsafe mode 且需要显式确认

• Extreme 风险操作始终不允许

#### 确认流程的工作原理

任何高风险操作（无论是 postgresql 还是 api request）即使在 unsafe 模式下也会被拦截。
!Every high-risk operation is blocked
您必须对每个高风险操作进行显式确认和批准才能执行。
!Explicit approval is always required

Changelog- 📦 通过 package manager 简化安装 - ✅ (v0.2.0)

• 🌎 支持不同的 Supabase regions - ✅ (v0.2.2)

• 🎮 带有安全控制的 Supabase management API 编程访问 - ✅ (v0.3.0)

• 👷‍♂️ 带有安全控制的数据库 SQL 只读和读写查询 - ✅ (v0.3.0)

• 🔄 针对直接连接和 pooled connections 的鲁棒事务处理 - ✅ (v0.3.2)

• 🐍 支持 native Python SDK 中的方法和对象 - ✅ (v0.3.6)

• 🔍 更强的 SQL 查询验证 ✅ (v0.3.8)

• 📝 数据库变更的自动版本控制 ✅ (v0.3.8)

• 📖 大幅改进 api spec 的知识库和工具 ✅ (v0.3.8)

• ✍️ 提高迁移相关工具的一致性，以实现更规范的数据库 vcs ✅ (v0.3.10)

• 🥳 Query MCP 正式发布 (v0.4.0)

如需更详细的 roadmap，请参阅 GitHub 上的此 discussion。

Star History


---

Enjoy! ☺️