Query | Supabase 的 MCP 服务器

🌅 通过 PyPI 安装超过 17,000 次，在 Smithery.ai 上的下载量接近 30,000 次——总之，这真是一次愉快的经历！🥳 感谢过去几个月来一直使用这款服务器的各位，希望它对你们有所帮助。 由于 Supabase 已经发布了他们自己的官方 MCP 服务器， 我决定不再积极维护这个版本。官方 MCP 服务器功能同样丰富，未来还将添加更多功能。快来试试吧！

Query MCP 是一个开源的 MCP 服务器，可以让您的 IDE 安全地执行 SQL、管理模式变更、调用 Supabase 管理 API，并使用 Auth Admin SDK —— 所有这些都内置了安全控制机制。

目录

开始使用 • 功能概览 • 故障排除 • 更新日志

✨ 核心特性

• 💻 兼容 Cursor、Windsurf、Cline 等支持 stdio 协议的 MCP 客户端
• 🔐 控制 SQL 查询的只读与读写模式
• 🔍 运行时 SQL 查询验证及风险等级评估
• 🛡️ 针对 SQL 操作的三层安全系统：安全、写入和破坏性
• 🔄 强大的事务处理能力，适用于直接连接和连接池方式
• 📝 自动为数据库模式变更添加版本号
• 💻 使用 Supabase 管理 API 管理您的 Supabase 项目
• 🧑‍💻 通过 Python SDK 使用 Supabase Auth Admin 方法管理用户
• 🔨 内置工具帮助 Cursor 和 Windsurf 更高效地使用 MCP
• 📦 通过包管理器（uv、pipx 等）实现极简安装与配置

开始使用

前提条件

安装该服务器需要在您的系统上具备以下内容：

• Python 3.12+

如果您计划通过 uv 安装，请确保已按照说明完成安装。

PostgreSQL 安装

对于 MCP 服务器本身而言，现在已不再需要安装 PostgreSQL，因为它使用的是 asyncpg，而 asyncpg 不依赖于 PostgreSQL 的开发库。

然而，如果您正在运行本地 Supabase 实例，则仍需安装 PostgreSQL：

MacOS

brew install postgresql@16

Windows

• 从 https://www.postgresql.org/download/windows/ 下载并安装 PostgreSQL 16 或更高版本
• 确保在安装过程中选择“PostgreSQL Server”和“Command Line Tools”

第一步：安装

自 v0.2.0 版本起，我引入了包安装支持。您可以使用自己喜欢的 Python 包管理器来安装该服务器：

# 如果已安装 pipx（推荐）
pipx install supabase-mcp-server

# 如果已安装 uv
uv pip install supabase-mcp-server

推荐使用 pipx，因为它会为每个包创建独立的环境。

您也可以手动安装：克隆仓库后，在根目录下运行 pipx install -e .。

从源码安装

如果您想从源码安装，例如用于本地开发：

uv venv
# 在 Mac 上
source .venv/bin/activate
# 在 Windows 上
.venv\Scripts\activate
# 以可编辑模式安装包
uv pip install -e .

通过 Smithery.ai 安装

有关如何使用 Smithery.ai 连接到此 MCP 服务器的完整说明，请参阅这里。

第 2 步：配置

Supabase MCP 服务器需要进行配置，以连接到您的 Supabase 数据库、访问管理 API 并使用 Auth Admin SDK。本节将介绍所有可用的配置选项及其设置方法。

🔑 重要提示：自 v0.4 版本起，MCP 服务器需要一个 API 密钥，您可以在 thequery.dev 上免费获取该密钥，才能使用此 MCP 服务器。

环境变量

服务器使用以下环境变量：

变量	必需	默认值	描述
SUPABASE_PROJECT_REF	是	127.0.0.1:54322	您的 Supabase 项目引用 ID（或本地主机：端口）
SUPABASE_DB_PASSWORD	是	postgres	您的数据库密码
SUPABASE_REGION	是*	us-east-1	您的 Supabase 项目托管的 AWS 区域
SUPABASE_ACCESS_TOKEN	否	无	Supabase 管理 API 的个人访问令牌
SUPABASE_SERVICE_ROLE_KEY	否	无	Auth Admin SDK 的服务角色密钥
QUERY_API_KEY	是	无	来自 thequery.dev 的 API 密钥（所有操作均需）

注意：默认值适用于本地 Supabase 开发环境。对于远程 Supabase 项目，您必须为 SUPABASE_PROJECT_REF 和 SUPABASE_DB_PASSWORD 提供您自己的值。

🚨 关键配置说明：对于远程 Supabase 项目，您必须使用 SUPABASE_REGION 指定项目实际所在的正确区域。如果您遇到“未找到租户或用户”的错误，这几乎可以肯定是由于您的区域设置与项目实际区域不符所致。您可以在 Supabase 控制台的“项目设置”中找到项目的区域。

连接类型

数据库连接

• 服务器通过事务池端点连接到您的 Supabase PostgreSQL 数据库。
• 本地开发使用直接连接到 127.0.0.1:54322。
• 远程项目使用格式：postgresql://postgres.[project_ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres。

⚠️ 重要提示：不支持会话池连接。服务器仅使用事务池连接，以更好地兼容 MCP 服务器架构。

管理 API 连接

• 需要设置 SUPABASE_ACCESS_TOKEN。
• 连接到 https://api.supabase.com 的 Supabase 管理 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 服务器实例使用：

# 创建配置目录
# macOS/Linux
mkdir -p ~/.config/supabase-mcp
# Windows (PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp"

# 创建并编辑 .env 文件
# macOS/Linux
nano ~/.config/supabase-mcp/.env
# Windows (PowerShell)
notepad "$env:APPDATA\supabase-mcp\.env"

将您的配置值添加到文件中：

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

方法 3：项目特定配置（仅限源码安装）

如果您是从源码运行服务器（而非通过软件包），则可以在项目目录中创建一个格式相同的 .env 文件。

查找您的 Supabase 项目信息

• 项目引用：可在您的 Supabase 项目 URL 中找到：https://supabase.com/dashboard/project/<project-ref>。
• 数据库密码：在项目创建时设置，或在“项目设置”→“数据库”中找到。
• 访问令牌：可在 https://supabase.com/dashboard/account/tokens 生成。
• 服务角色密钥：可在“项目设置”→“API”→“项目 API 密钥”中找到。

支持的区域

服务器支持所有 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 托管项目及本地开发。
• 不支持自定义连接字符串：不支持自定义连接字符串。
• 仅支持事务池连接：数据库连接仅支持事务池模式。
• API 和 SDK 功能限制：管理 API 和 Auth Admin SDK 功能仅适用于远程 Supabase 项目，不适用于本地开发。

第 3 步：使用

一般来说，任何支持 stdio 协议的 MCP 客户端都应能与本 MCP 服务器配合使用。本服务器已明确测试可与以下客户端配合使用：

• Cursor
• Windsurf
• Cline
• Claude Desktop

此外，您还可以使用 smithery.ai 来安装本服务器以及上述多个客户端。

请按照以下指南，在您的客户端中安装本 MCP 服务器。

Cursor

前往“设置”→“功能”→“MCP 服务器”，并添加一个新服务器，配置如下：

# 可设置为任意名称
name: supabase
type: command
# 如果您使用 pipx 安装
command: supabase-mcp-server
# 如果您使用 uv 安装
command: uv run supabase-mcp-server

# 如果上述方法无效，请使用完整路径（推荐）
命令：/full/path/to/supabase-mcp-server  # 使用 'which supabase-mcp-server'（macOS/Linux）或 'where supabase-mcp-server'（Windows）查找

如果配置正确，您应该会看到一个绿色的点状指示器以及服务器暴露的工具数量。

Windsurf

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

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // 更新路径
        "env": {
          "QUERY_API_KEY": "your-api-key",  // 必填项 - 请在 thequery.dev 获取您的 API 密钥
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // 可选，默认为 us-east-1
          "SUPABASE_ACCESS_TOKEN": "your-access-token",  // 可选，用于管理 API
          "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // 可选，用于 Auth Admin SDK
        }
      }
    }
}

如果配置正确，您应该会看到绿色的点状指示器，并且在可用服务器列表中可以点击 Supabase 服务器。

Claude Desktop

Claude Desktop 也支持通过 JSON 配置来使用 MCP 服务器。请按照以下步骤设置 Supabase MCP 服务器：

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

   # 在 macOS/Linux 上
   which supabase-mcp-server
   
   # 在 Windows 上
   where supabase-mcp-server
   

   复制返回的完整路径（例如：/Users/username/.local/bin/supabase-mcp-server）。

2. 在 Claude Desktop 中配置 MCP 服务器：

   • 打开 Claude Desktop
   • 进入设置 → 开发者 → 编辑配置 MCP 服务器
   • 添加新的配置，内容如下：

   {
     "mcpServers": {
       "supabase": {
         "command": "/full/path/to/supabase-mcp-server",  // 替换为步骤 1 中的实际路径
         "env": {
           "QUERY_API_KEY": "your-api-key",  // 必填项 - 请在 thequery.dev 获取您的 API 密钥
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",  // 可选，默认为 us-east-1
           "SUPABASE_ACCESS_TOKEN": "your-access-token",  // 可选，用于管理 API
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // 可选，用于 Auth Admin SDK
         }
       }
     }
   }
   

⚠️ 重要提示：与 Windsurf 和 Cursor 不同，Claude Desktop 需要提供可执行文件的 完整绝对路径。仅使用命令名称（supabase-mcp-server）会导致“spawn ENOENT”错误。

如果配置正确，您应该会在 Claude Desktop 中看到 Supabase MCP 服务器已列出并可供使用。

Cline

Cline 同样支持通过类似的 JSON 配置来使用 MCP 服务器。请按照以下步骤设置 Supabase MCP 服务器：

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

   # 在 macOS/Linux 上
   which supabase-mcp-server
   
   # 在 Windows 上
   where supabase-mcp-server
   

   复制返回的完整路径（例如：/Users/username/.local/bin/supabase-mcp-server）。

2. 在 Cline 中配置 MCP 服务器：

   • 打开 VS Code 中的 Cline
   • 点击 Cline 侧边栏中的“MCP 服务器”选项卡
   • 点击“配置 MCP 服务器”
   • 这将打开 cline_mcp_settings.json 文件
   • 添加以下配置：

   {
     "mcpServers": {
       "supabase": {
         "command": "/full/path/to/supabase-mcp-server",  // 替换为步骤 1 中的实际路径
         "env": {
           "QUERY_API_KEY": "your-api-key",  // 必填项 - 请在 thequery.dev 获取您的 API 密钥
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",  // 可选，默认为 us-east-1
           "SUPABASE_ACCESS_TOKEN": "your-access-token",  // 可选，用于管理 API
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // 可选，用于 Auth Admin SDK
         }
       }
     }
   }
   

如果配置正确，您应该会在 Cline 的 MCP 服务器列表中看到 Supabase MCP 服务器旁边的绿色指示灯，同时面板底部会显示“supabase MCP 服务器已连接”的确认信息。

故障排除

以下是一些可能对您有帮助的技巧和提示：

• 调试安装：直接在终端运行 supabase-mcp-server，看看是否能正常工作。如果不能，则可能是安装存在问题。
• MCP 服务器配置：如果上述步骤能够成功运行，说明服务器已正确安装和配置。只要您提供了正确的命令，IDE 就应该能够连接。请务必提供服务器可执行文件的正确路径。
• “未找到工具”错误：如果在 Cursor 中即使已安装该包仍显示“客户端已关闭 - 没有可用工具”：
  • 使用 which supabase-mcp-server（macOS/Linux）或 where supabase-mcp-server（Windows）找到可执行文件的完整路径
  • 在 MCP 服务器配置中使用完整路径，而不是仅使用 supabase-mcp-server
  • 例如：/Users/username/.local/bin/supabase-mcp-server 或 C:\Users\username\.local\bin\supabase-mcp-server.exe
• 环境变量：为了连接到正确的数据库，请确保在 mcp_config.json 或全局配置目录下的 .env 文件中设置环境变量（macOS/Linux 为 ~/.config/supabase-mcp/.env，Windows 为 %APPDATA%\supabase-mcp\.env）。
• 访问日志：MCP 服务器会将详细日志写入文件：
  • 日志文件位置：
    • macOS/Linux：~/.local/share/supabase-mcp/mcp_server.log
    • Windows：%USERPROFILE%\.local\share\supabase-mcp\mcp_server.log
  • 日志内容包括连接状态、配置详情以及操作结果
  • 可以使用任何文本编辑器或终端命令查看日志：

    # 在 macOS/Linux 上
    cat ~/.local/share/supabase-mcp/mcp_server.log
    
    # 在 Windows 上（PowerShell）
    Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"
    

如果您遇到困难或以上任何说明不正确，请提交问题。

MCP 检查器

一个非常有用的工具，可以帮助调试 MCP 服务器问题，就是 MCP 检查器。如果你是从源码安装的，可以直接在项目仓库中运行 supabase-mcp-inspector，它就会启动检查器实例。配合日志使用，你可以全面了解服务器中正在发生的事情。

📝 如果是从软件包安装的，运行 supabase-mcp-inspector 可能无法正常工作——我将在即将发布的版本中进行验证并修复。

功能概览

数据库查询工具

自 v0.3+ 版本起，服务器提供了全面的数据库管理功能，并内置了安全控制机制：

• SQL 查询执行：执行 PostgreSQL 查询并进行风险评估

  • 三层安全系统：
    • safe：只读操作（SELECT）——始终允许
    • write：数据修改操作（INSERT、UPDATE、DELETE）——需要切换到非安全模式
    • destructive：模式变更操作（DROP、CREATE）——需要切换到非安全模式并确认

• SQL 解析与验证：

  • 使用 PostgreSQL 的解析器（pglast）进行准确分析，并提供清晰的安全性要求反馈

• 自动迁移版本管理：

  • 所有会改变数据库结构的操作都会自动版本化
  • 根据操作类型和目标生成描述性的名称

• 安全控制：

  • 默认 SAFE 模式仅允许只读操作
  • 所有语句都通过 asyncpg 在事务模式下执行
  • 高风险操作需经过两步确认

• 可用工具：

  • get_schemas：列出所有模式及其大小和表数量
  • get_tables：列出所有表、外部表和视图及其元数据
  • get_table_schema：获取详细的表结构信息（列、键、关系等）
  • execute_postgresql：对数据库执行 SQL 语句
  • confirm_destructive_operation：在确认后执行高风险操作
  • retrieve_migrations：获取迁移记录，并支持筛选和分页
  • live_dangerously：在安全模式和非安全模式之间切换

管理 API 工具

自 v0.3.0 版本起，服务器提供了对 Supabase 管理 API 的安全访问，并内置了安全控制机制：

• 可用工具：

  • send_management_api_request：向 Supabase 管理 API 发送任意请求，并自动注入项目引用
  • get_management_api_spec：获取包含安全信息的丰富 API 规范
    • 支持多种查询模式：按域名、按特定路径/方法或查询所有路径
    • 包含每个端点的风险评估信息
    • 提供详细的参数要求和响应格式
    • 帮助 LLMs 理解 Supabase 管理 API 的全部能力
  • get_management_api_safety_rules：获取所有安全规则，并附有人类可读的解释
  • live_dangerously：在安全模式和非安全模式之间切换

• 安全控制：

  • 使用与数据库操作相同的安全管理器，以实现一致的风险管理
  • 操作按风险级别分类：
    • safe：只读操作（GET）——始终允许
    • unsafe：状态变更操作（POST、PUT、PATCH、DELETE）——需要切换到非安全模式
    • blocked：破坏性操作（删除项目等）——绝不允许
  • 默认安全模式可防止意外的状态变更
  • 基于路径的模式匹配用于制定精确的安全规则

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

Auth Admin 工具

我原本计划将 Python SDK 方法的支持添加到 MCP 服务器中。但经过考虑，我决定只支持 Auth Admin 方法，因为我经常手动创建测试用户，这既容易出错又耗时。现在，我只需让 Cursor 创建一个测试用户，一切就能无缝完成。请查看完整的 Auth Admin SDK 方法文档，了解其功能。

自 v0.3.6 版本起，服务器支持通过 Python SDK 直接访问 Supabase Auth Admin 方法：

• 包括以下工具：
  • 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：删除用户的某个认证因素（目前 SDK 中尚未实现）

为什么使用 Auth Admin SDK 而不是直接使用 SQL 查询？

Auth Admin SDK 相比直接操作 SQL 具有以下几大优势：

• 功能：能够执行 SQL 无法单独完成的操作（邀请、魔法链接、MFA 等）

• 准确性：比直接在认证模式上编写和执行 SQL 查询更可靠

• 简洁性：提供清晰的方法，并具备完善的验证和错误处理机制

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

日志与分析

服务器提供了对 Supabase 日志和分析数据的访问权限，使你更容易监控和排查应用程序中的问题：

• 可用工具：retrieve_logs——访问任何 Supabase 服务的日志

• 日志集合：

  • postgres：数据库服务器日志
  • api_gateway：API 网关请求日志
  • auth：身份验证事件日志
  • postgrest：RESTful API 服务日志
  • pooler：连接池日志
  • storage：对象存储操作日志
  • realtime：WebSocket 订阅日志
  • edge_functions：无服务器函数执行日志
  • cron：定时任务日志
  • pgbouncer：连接池日志

• 功能：可以按时间过滤、搜索文本、应用字段筛选，或使用自定义 SQL 查询。 这简化了在整个 Supabase 技术栈中的调试工作，无需在不同界面之间切换或编写复杂的查询。

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

“能力越大，责任越大。” 尽管 execute_postgresql 工具配合名为 live_dangerously 的工具，为管理您的 Supabase 数据库提供了一种强大而简便的方式，但也意味着只需一条聊天消息，就可能删除或修改表。为了降低不可逆更改的风险，自 v0.3.8 版本起，服务器支持以下功能：

• 自动为所有在数据库上执行的写入及破坏性 SQL 操作生成迁移脚本
• 改进的查询执行安全模式，在该模式下，所有查询被划分为：
  • “安全”类型：始终允许。包括所有只读操作。
  • “写入”类型：需要用户启用“写入”模式。
  • “破坏性”类型：需要用户启用“写入”模式，并且对于不自动执行工具的客户端，还需进行两步确认才能执行查询。

通用安全模式

自 v0.3.8 版本起，安全模式已在所有服务（数据库、API、SDK）中标准化，采用统一的安全管理器。这提供了连贯的风险管理机制，并为在整个 MCP 服务器上控制安全设置提供了一个统一的接口。

所有操作（SQL 查询、API 请求、SDK 方法）均按风险等级分类：

• 低风险：只读操作，不会修改数据或结构（SELECT 查询、GET API 请求）
• 中风险：写入操作，会修改数据但不改变结构（INSERT/UPDATE/DELETE，大多数 POST/PUT API 请求）
• 高风险：破坏性操作，会修改数据库结构或可能导致数据丢失（DROP/TRUNCATE，DELETE API 端点）
• 极高风险：后果极其严重、完全禁止的操作（删除项目）

安全控制根据风险等级实施：

• 低风险操作始终允许
• 中风险操作需启用非安全模式
• 高风险操作需启用非安全模式并进行明确确认
• 极高风险操作一律禁止

确认流程的工作方式

任何高风险操作（无论是 PostgreSQL 还是 API 请求）即使在“非安全”模式下也会被阻止。 您必须对每一项高风险操作进行明确确认并批准，它才会被执行。

更改日志

• 📦 通过包管理器简化安装 — ✅（v0.2.0）
• 🌎 支持不同的 Supabase 区域 — ✅（v0.2.2）
• 🎮 带有安全控制的 Supabase 管理 API 编程式访问 — ✅（v0.3.0）
• 👷‍♂️ 带有安全控制的只读和读写数据库 SQL 查询 — ✅（v0.3.0）
• 🔄 强健的事务处理，适用于直接连接和连接池 — ✅（v0.3.2）
• 🐍 支持原生 Python SDK 中可用的方法和对象 — ✅（v0.3.6）
• 🔍 更强的 SQL 查询验证 — ✅（v0.3.8）
• 📝 数据库变更的自动版本控制 — ✅（v0.3.8）
• 📖 大幅改进的 API 规范知识与工具 — ✅（v0.3.8）
• ✍️ 改进迁移相关工具的一致性，以实现更有序的数据库版本控制系统 — ✅（v0.3.10）
• 🥳 Query MCP 正式发布 — （v0.4.0）

如需更详细的路线图，请参阅 GitHub 上的此讨论。

星标历史

---

祝您使用愉快！☺️

Supabase MCP Server 快速上手指南

重要提示：本项目作者已停止维护，因为 Supabase 官方发布了 官方 MCP Server。建议新用户优先尝试官方版本。若需继续使用本工具，请参考以下指南。

Query MCP 是一个开源的 MCP 服务器，允许你的 IDE（如 Cursor、Windsurf）安全地执行 SQL、管理架构变更、调用 Supabase 管理 API 以及使用 Auth Admin SDK。

环境准备

在开始之前，请确保你的系统满足以下要求：

• Python 版本：必须安装 Python 3.12 或更高版本。
• 包管理器（推荐）：推荐安装 uv 或 pipx 以隔离环境。
  • 安装 uv: 参考 uv 安装文档
  • 安装 pipx: pip install pipx && pipx ensurepath
• PostgreSQL（仅本地开发需要）：如果你运行的是本地 Supabase 实例，需要安装 PostgreSQL 16+。
  • macOS: brew install postgresql@16
  • Windows: 从官网下载并安装，确保勾选 "PostgreSQL Server" 和 "Command Line Tools"。
  • 注：连接远程 Supabase 项目无需在本地安装 PostgreSQL。

安装步骤

推荐使用 pipx 进行安装，它会自动创建独立的虚拟环境，避免依赖冲突。

方式一：使用 pipx（推荐）

pipx install supabase-mcp-server

方式二：使用 uv

uv pip install supabase-mcp-server

方式三：源码安装（用于开发）

git clone https://github.com/alexander-zuev/supabase-mcp-server.git
cd supabase-mcp-server
uv venv
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate
uv pip install -e .

配置与使用

1. 获取必要凭证

自 v0.4 版本起，使用该服务器必须拥有一个 API Key。

• QUERY_API_KEY: 前往 thequery.dev 免费获取。
• Supabase 项目信息:
  • SUPABASE_PROJECT_REF: 项目 URL 中的 ID (例如 https://supabase.com/dashboard/project/<ref> 中的 <ref>)。
  • SUPABASE_DB_PASSWORD: 在 Project Settings -> Database 中查看。
  • SUPABASE_REGION: 项目所在的 AWS 区域 (默认为 us-east-1，务必与实际区域一致，否则报错)。
  • SUPABASE_ACCESS_TOKEN (可选): 用于管理 API，在 Account Tokens 生成。
  • SUPABASE_SERVICE_ROLE_KEY (可选): 用于 Auth 管理，在 Project Settings -> API 中查看。

2. 设置环境变量

由于通过 pipx 或 uv 安装时无法读取项目目录下的 .env 文件，推荐以下两种配置方式：

方案 A：全局配置文件（推荐）

创建一个全局配置文件，所有 MCP 实例均可读取。

macOS / Linux:

mkdir -p ~/.config/supabase-mcp
nano ~/.config/supabase-mcp/.env

Windows (PowerShell):

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

在文件中填入以下内容：

QUERY_API_KEY=your-api-key-from-thequery
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

方案 B：客户端直接配置

在 IDE 的 MCP 设置中直接传入环境变量（见下文）。

3. 在 IDE 中集成

本服务器支持任何使用 stdio 协议的 MCP 客户端。以下是 Cursor 的配置示例：

1. 打开 Cursor 设置：Settings -> Features -> MCP Servers。
2. 点击 Add New Server。
3. 填写如下配置：

{
  "name": "supabase",
  "type": "command",
  "command": "supabase-mcp-server",
  "env": {
    "QUERY_API_KEY": "your-api-key-from-thequery",
    "SUPABASE_PROJECT_REF": "your-project-ref",
    "SUPABASE_DB_PASSWORD": "your-db-password",
    "SUPABASE_REGION": "us-east-1"
  }
}

注意：如果 command 直接使用 supabase-mcp-server 无效，请使用绝对路径。

• macOS/Linux 查找路径：which supabase-mcp-server
• Windows 查找路径：where supabase-mcp-server

若使用 uv 安装，命令可改为：

"command": "uv",
"args": ["run", "supabase-mcp-server"]

4. 验证使用

配置完成后，IDE 中的 MCP 状态指示器应变为绿色。你可以在聊天窗口中尝试以下自然语言指令：

• "列出当前数据库中的所有表"
• "创建一个名为 users 的新表，包含 id 和 email 字段"
• "查询最近注册的用户"

服务器将自动评估 SQL 的安全等级（只读、写入或破坏性操作）并执行。