Query | MCP server for Supabase

Query | Supabase 的 MCP 服务

🌅 通过 PyPI 安装超过 1.7 万次，在 Smithery.ai 上的下载量接近 3 万次——简而言之，这段经历很有趣！🥳 感谢过去几个月一直使用此服务的各位，希望它对你有所帮助。 自从 Supabase 发布了自己的官方 MCP 服务后， 我决定不再积极维护这个服务。官方 MCP 服务的功能同样丰富，未来还会添加更多 功能。欢迎了解！

Query MCP 是一个开源 MCP 服务，可让你的 IDE 安全地运行 SQL、管理架构更改、调用 Supabase Management API 并使用 Auth Admin SDK，且内置安全控制。

目录

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

✨ 主要功能

• 💻 兼容 Cursor、Windsurf、Cline 以及其他支持 stdio 协议的 MCP 客户端
• 🔐 控制 SQL 查询执行的只读和读写模式
• 🔍 在运行时验证 SQL 查询并评估风险等级
• 🛡️ SQL 操作的三级安全体系：安全、写入和破坏性操作
• 🔄 为直接连接和连接池数据库连接提供可靠的事务处理
• 📝 自动为数据库架构更改添加版本记录
• 💻 使用 Supabase Management API 管理 Supabase 项目
• 🧑‍💻 通过 Python SDK 使用 Supabase Auth Admin 方法管理用户
• 🔨 预构建工具，帮助 Cursor 和 Windsurf 更有效地使用 MCP
• 📦 通过包管理器（uv、pipx 等）轻松安装和设置

开始使用

前提条件

安装此服务需要系统满足以下条件：

• Python 3.12+

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

安装 PostgreSQL

MCP 服务本身不再需要安装 PostgreSQL，因为现在使用的 asyncpg 不依赖 PostgreSQL 开发库。

不过，如果你要运行本地 Supabase 实例，仍然需要 PostgreSQL：

MacOS

brew install postgresql@16

Windows

• 从 https://www.postgresql.org/download/windows/ 下载并安装 PostgreSQL 16+
• 安装时确保选中“PostgreSQL Server”和“Command Line Tools”

步骤 1. 安装

从 v0.2.0 开始，我添加了对软件包安装的支持。你可以使用喜欢的 Python 软件包管理器，通过以下方式安装服务：

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

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

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

你也可以通过克隆仓库并在根目录下运行 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 安装

你可以在此处查看如何使用 Smithery.ai 连接到此 MCP 服务的完整说明。

步骤 2. 配置

Supabase MCP 服务需要进行配置，才能连接到 Supabase 数据库、访问 Management 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 Management 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 控制台的 Project Settings 中查看项目所在区域。

连接类型

数据库连接

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

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

Management 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

选项 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 服务”，并使用以下配置添加新服务：

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

如果配置正确，你应该会看到绿色圆点指示器，以及可用服务列表中可点击的 supabase 服务。

Claude Desktop

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

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

   # On macOS/Linux
   which supabase-mcp-server
   
   # On Windows
   where supabase-mcp-server
   

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

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

   • 打开 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
         }
       }
     }
   }
   

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

如果配置正确，你应该会在 Claude Desktop 中看到 Supabase MCP 服务列为可用服务。

Cline

Cline 也支持通过类似的 JSON 配置 MCP 服务。按照以下步骤设置 Supabase MCP 服务：

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

   # On macOS/Linux
   which supabase-mcp-server
   
   # On Windows
   where supabase-mcp-server
   

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

2. 在 Cline 中配置 MCP 服务：

   • 在 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
         }
       }
     }
   }
   

如果配置正确，你应该会在 Cline 的 MCP Servers 列表中看到 Supabase MCP 服务旁边的绿色指示器，并在面板底部看到确认消息“supabase MCP server connected”。

故障排除

以下提示和技巧或许能帮到你：

• 调试安装 - 在终端中直接运行 supabase-mcp-server，查看是否正常工作。如果不正常，可能是安装出了问题。
• MCP 服务配置 - 如果上一步正常工作，说明服务已正确安装和配置。只要你提供了正确的命令，IDE 就应该能够连接。请确保提供服务可执行文件的正确路径。
• “No tools found” 错误 - 如果软件包已安装，但你在 Cursor 中看到 “Client closed - no tools available”：
  • 运行 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"
    

如果你遇到问题，或发现上述说明有误，请提交 issue。

MCP Inspector

MCP Inspector 是一款非常实用的工具，可帮助调试 MCP 服务问题。如果你从源码安装，可在项目仓库中运行 supabase-mcp-inspector 来启动 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：在安全和不安全模式之间切换

Management API 工具

自 v0.3.0 起，服务端通过内置安全控制，支持安全地访问 Supabase Management API：

• 可用工具：

  • send_management_api_request：向 Supabase Management API 发送任意请求，并自动注入项目 ref
  • get_management_api_spec：获取包含安全信息的增强版 API 规范
    • 支持多种查询模式：按域名、特定路径／方法或所有路径查询
    • 包含每个端点的风险评估信息
    • 提供详细的参数要求和响应格式
    • 帮助 LLM 了解 Supabase Management API 的全部功能
  • get_management_api_safety_rules：获取所有安全规则及其通俗易懂的说明
  • live_dangerously：在安全和不安全操作模式之间切换

• 安全控制：

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

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

Auth Admin 工具

我原本打算为 MCP 服务添加对 Python SDK 方法的支持。经过考虑，我决定仅支持 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 查询？

与直接操作 SQL 相比，Auth Admin SDK 具有以下几个主要优势：

• 功能：支持仅靠 SQL 无法实现的操作（邀请、魔法链接、MFA）

• 准确性：比创建并执行针对 auth 架构的原始 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 操作自动创建迁移脚本
• 改进查询执行安全模式，将所有查询分类为：
  • safe 类型：始终允许。包括所有只读操作。
  • write类型：要求用户启用 write 模式。
  • destructive 类型：要求用户启用 write 模式；对于不会自动执行工具的客户端，还要求分两步确认执行查询。

通用安全模式

从 v0.3.8 起，所有服务（数据库、API、SDK）均通过通用安全管理器统一采用安全模式。这为整个 MCP 服务提供一致的风险管理方式和统一的安全设置控制界面。

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

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

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

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

确认流程的运作方式

任何高风险操作（无论是 PostgreSQL 还是 API 请求）即使在 unsafe 模式下也会被阻止。 每次执行高风险操作前，都必须明确确认并批准。

更新日志

• 📦 通过包管理器简化安装 - ✅ (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 上的这篇讨论。

Star 历史

---

祝使用愉快！☺️