MCP 服务器

Query MCP

启用 IDE 对 Supabase 数据库的访问，包括 SQL 查询执行、模式管理、Auth 管理员操作，以及内置的安全控制，以防止意外的破坏性操作。

README

查询 MCP (Supabase MCP 服务器)

使您最喜欢的 IDE 能够安全地执行 SQL 查询，端到端地管理您的数据库，访问管理 API，并通过内置的安全控制处理用户身份验证。

🎉 Supabase MCP 服务器的未来 -> Query MCP

我很高兴地宣布 Supabase MCP 服务器正在演变为 thequery.dev！

虽然我对未来有宏伟的计划，但我希望明确以下承诺：

核心工具将永远保持免费 - 免费和开源软件是我进入编码的方式
将在其上添加高级功能 - 增强功能，而不限制现有功能
前 2,000 名早期采用者将获得特殊福利 - 尽早加入以获得独家待遇！

🚀 重大 v4 发布即将推出！

👉 在 thequery.dev 加入早期访问

✨ 主要功能

💻 兼容 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，后者不依赖于 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 包管理器通过以下方式安装服务器：

# 如果安装了 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。本节介绍所有可用的配置选项以及如何设置它们。

环境变量

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

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

注意：默认值配置为用于本地 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

配置方法

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

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

⚠️ 重要提示：当使用通过 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"

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

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

# 可以设置为任何名称
name: supabase
type: command
# 如果您使用 pipx 安装
command: supabase-mcp-server
# 如果您使用 uv 安装
command: uv run supabase-mcp-server
# 如果以上方法不起作用，请使用完整路径（推荐）
command: /full/path/to/supabase-mcp-server  # 使用 'which supabase-mcp-server' (macOS/Linux) 或 'where supabase-mcp-server' (Windows) 查找

如果配置正确，您应该会看到一个绿色圆点指示器以及服务器公开的工具数量。成功的 Cursor 配置的外观

Windsurf

转到 Cascade -> 单击锤子图标 -> 配置 -> 填写配置：

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // 更新路径
        "env": {
          "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 服务器。

成功的 Windsurf 配置的外观

Claude Desktop

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

找到可执行文件的完整路径（此步骤至关重要）：
```
# 在 macOS/Linux 上
which supabase-mcp-server

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

在 Claude Desktop 中配置 MCP 服务器：

打开 Claude Desktop
转到设置 → 开发者 -> 编辑配置 MCP 服务器
添加具有以下 JSON 的新配置：

{
  "mcpServers": {
    "supabase": {
      "command": "/full/path/to/supabase-mcp-server",  // 替换为步骤 1 中的实际路径
      "env": {
        "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 服务器列为可用。

成功的 Windsurf 配置的外观

Cline

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

找到可执行文件的完整路径（此步骤至关重要）：
```
# 在 macOS/Linux 上
which supabase-mcp-server

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

在 Cline 中配置 MCP 服务器：

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

{
  "mcpServers": {
    "supabase": {
      "command": "/full/path/to/supabase-mcp-server",  // 替换为步骤 1 中的实际路径
      "env": {
        "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 服务器已连接”。

Cline 中成功的配置的外观

故障排除

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

调试安装 - 直接从终端运行 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 文件中设置了 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 在事务模式下运行
- 对高风险操作进行 2 步确认
可用工具：
- 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 规范
  - 支持多种查询模式：按域、按特定路径/方法或所有路径
  - 包括每个端点的风险评估信息
  - 提供详细的参数要求和响应格式
  - 帮助 LLM 了解 Supabase 管理 API 的全部功能
- get_management_api_safety_rules：获取具有人类可读解释的所有安全规则
- live_dangerously：在安全和不安全操作模式之间切换
安全控制：
- 使用与数据库操作相同的安全管理器来实现一致的风险管理
- 操作按风险级别分类：
  - safe：只读操作 (GET) - 始终允许
  - unsafe：更改状态的操作（POST、PUT、PATCH、DELETE）- 需要不安全模式
  - blocked：破坏性操作（删除项目等）- 永远不允许
- 默认安全模式可防止意外的状态更改
- 基于路径的模式匹配，用于精确的安全规则

注意：管理 API 工具仅适用于远程 Supabase 实例，并且与本地 Supabase 开发设置不兼容。

Auth Admin 工具

我计划向 MCP 服务器添加对 Python SDK 方法的支持。经过考虑，我决定仅添加对 Auth 管理员方法的支持，因为我经常发现自己手动创建测试用户，这很容易出错且耗时。现在，我可以要求 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）
准确性：比在 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 模式，并且对于不自动执行工具的客户端，需要对查询执行进行 2 步确认。

通用安全模式

自 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 风险：具有严重后果的操作，完全被阻止（删除项目）

安全控制基于风险级别应用：

始终允许低风险操作
中等风险操作需要启用不安全模式
高风险操作需要启用不安全模式和显式确认
永远不允许极高风险操作

确认流程如何工作

即使在 unsafe 模式下，任何高风险操作（无论是 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)
✍️ 改进了与迁移相关的工具的一致性，以实现更井然有序的数据库 vcs ✅ (v0.3.10)

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

Star 历史

尽情享受！☺️