查询 | Supabase 的 MCP 服务器

🌅 通过 pypi 安装量超过 1.7 万次，在 Smithery.ai 上的下载量接近 3 万次——总之，这真是太有趣了！🥳 感谢过去几个月使用这个服务器的所有人，希望它对你们有所帮助。由于 Supabase 发布了他们自己的官方 MCP 服务器，我决定不再主动维护这个服务器。官方 MCP 服务器功能丰富，未来还会添加更多功能。快来体验吧！

✨ 主要特点

💻 兼容 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，因为它现在使用不依赖于 PostgreSQL 开发库的 asyncpg。

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

MacOS

brew install postgresql@16

视窗

从https://www.postgresql.org/download/windows/下载并安装 PostgreSQL 16+
确保在安装过程中选择了“PostgreSQL 服务器”和“命令行工具”

步骤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 管理 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
连接到 Supabase 管理 API，网址为https://api.supabase.com
仅适用于远程 Supabase 项目（不适用于本地开发）

Auth Admin SDK 连接

需要设置SUPABASE_SERVICE_ROLE_KEY
对于本地开发，连接到http://127.0.0.1:54321
对于远程项目，连接到https://[project_ref].supabase.co

配置方法

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

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

⚠️重要提示：使用通过 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 服务器兼容。此服务器已明确测试可与以下平台兼容：

光标
风帆冲浪
克莱恩
克劳德桌面

此外，您还可以使用 smithery.ai 为该服务器安装多个客户端，包括上述客户端。

按照以下指南在您的客户端安装此 MCP 服务器。

光标

转到设置 -> 功能 -> 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)

如果配置正确，您应该会看到一个绿点指示器和服务器公开的工具数量。成功的 Cursor 配置是什么样的

风帆冲浪

进入Cascade->点击锤子图标->配置->填写配置：

{ "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 服务器。

成功的 Windsurf 配置是什么样的

克劳德桌面

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

找到可执行文件的完整路径（此步骤至关重要）：
# On macOS/Linux which supabase-mcp-server # On Windows where supabase-mcp-server
复制返回的完整路径（例如， /Users/username/.local/bin/supabase-mcp-server ）。
在 Claude Desktop 中配置 MCP 服务器：
- 打开 Claude 桌面
- 前往“设置”→“开发者”→“编辑配置 MCP 服务器”
- 使用以下 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”错误。

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

成功的 Windsurf 配置是什么样的

克莱恩

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

找到可执行文件的完整路径（此步骤至关重要）：
# On macOS/Linux which supabase-mcp-server # On 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", // 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 服务器列表中的 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文件（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
- 日志包括连接状态、配置详情、操作结果
- 使用任何文本编辑器或终端命令查看日志：
  # 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 检查器

MCP Inspector 是一款非常实用的工具，可以帮助调试 MCP 服务器问题。如果您是从源代码安装的，则可以从项目仓库运行supabase-mcp-inspector ，它会运行检查器实例。结合日志，它可以让您全面了解服务器的运行情况。

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

功能概述

数据库查询工具

由于 v0.3+ 服务器提供了全面的数据库管理功能并内置了安全控制：

SQL 查询执行：执行 PostgreSQL 查询并进行风险评估
- 三层安全体系：
  - safe ：只读操作（SELECT）- 始终允许
  - write ：数据修改（插入、更新、删除） - 需要不安全模式
  - 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 Management 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 开发设置不兼容。

授权管理工具

我原本计划在 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）
准确性：比在身份验证模式上创建和执行原始 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风险：后果严重的操作将被彻底阻止（删除项目）

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

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

确认流程如何运作

即使在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）
🥳 查询 MCP 已发布 (v0.4.0)

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

星史

尽情享受吧！☺️