Supabase MCP 数据库服务器添加福利群:解决AI开发者的「MCP实战痛点」🌅 通过 pypi 安装了超过 17k 次,在 Smithery.ai 上接近 30k 次下载——简而言之,这很有趣!🥳 感谢过去几个月使用此服务器的每个人,我希望它对你们有用。 由于 Supabase 已经发布了他们自己的官方 MCP 服务器, 我决定不再积极维护这个服务器。官方 MCP 服务器功能丰富,未来还会添加更多功能。请查看!
Query MCP 是一个开源的 MCP 服务器,它可以让你的 IDE 安全地运行 SQL、管理模式更改、调用 Supabase 管理 API 并使用 Auth Admin SDK——所有这些都带有内置的安全控制。
stdio 协议的 MCP 客户端安装服务器需要你的系统满足以下条件:
如果你计划通过 uv 安装,请确保它已经安装。
MCP 服务器本身不再需要 PostgreSQL 安装,因为它现在使用 asyncpg,而 asyncpg 不依赖于 PostgreSQL 开发库。
但是,如果你正在运行本地 Supabase 实例,你仍然需要 PostgreSQL:
MacOS
brew install postgresql@16
Windows
从 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 连接到此 MCP 服务器的完整说明 这里
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指定你的项目所在的正确区域。如果你遇到 "Tenant or user not found" 错误,这几乎肯定是因为你的区域设置与项目的实际区域不匹配。你可以在 Supabase 仪表板的项目设置下找到你的项目区域。
127.0.0.1:54322postgresql://postgres.[project_ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres⚠️ 重要:不支持会话池连接。服务器专门使用事务池以获得更好的 MCP 服务器架构兼容性。
SUPABASE_ACCESS_TOKENhttps://api.supabase.comSUPABASE_SERVICE_ROLE_KEYhttp://127.0.0.1:54321https://[project_ref].supabase.co服务器按以下顺序查找配置(优先级从高到低):
.env 文件:当前工作目录中的 .env 文件(仅当从源代码运行时有效)%APPDATA%\supabase-mcp\.env~/.config/supabase-mcp/.env⚠️ 重要:当使用通过 pipx 或 uv 安装的包时,项目目录中的本地
.env文件不会被检测到。你必须使用环境变量或全局配置文件。
直接在 MCP 客户端配置中设置环境变量(参见步骤 3 中的客户端特定设置说明)。大多数 MCP 客户端支持这种方法,它可以将你的配置与客户端设置保持一致。
创建一个全局 .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=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 文件,格式与上述相同。
https://supabase.com/dashboard/project/<project-ref>服务器支持所有 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 - 南美(圣保罗)一般来说,任何支持 stdio 协议的 MCP 客户端都应该与此 MCP 服务器兼容。此服务器经过明确测试,可与以下客户端配合使用:
此外,你还可以使用 smithery.ai 在多个客户端中安装此服务器,包括上述客户端。
按照以下指南在你的客户端中安装此 MCP 服务器。
转到设置 -> 功能 -> 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)查找

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

转到 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 也通过 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 服务器:
{
"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 服务器列为可用。
Windsurf 成功配置的样子 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 服务器:
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 Servers 列表中 Supabase MCP 服务器旁边看到一个绿色指示器,并且在面板底部看到一条确认消息“supabase MCP server connected”。
这里有一些可能有帮助的提示和技巧:
supabase-mcp-server 查看其是否正常工作。如果无法运行,则安装可能存在问题。which supabase-mcp-server(macOS/Linux)或 where supabase-mcp-server(Windows)找到可执行文件的完整路径。supabase-mcp-server。/Users/username/.local/bin/supabase-mcp-server 或 C:\Users\username\.local\bin\supabase-mcp-server.exemcp_config.json 或全局配置目录(macOS/Linux 上为 ~/.config/supabase-mcp/.env,Windows 上为 %APPDATA%\supabase-mcp\.env)中的 .env 文件中设置环境变量。~/.local/share/supabase-mcp/mcp_server.log%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 服务器问题。如果您是从源码安装的,您可以从项目仓库运行 supabase-mcp-inspector,它将运行检查器实例。结合日志,这将使您全面了解服务器中发生的情况。
📝 如果从软件包安装,运行
supabase-mcp-inspector无法正常工作 - 我将在下一个版本中验证并修复此问题。
从 v0.3+ 版本开始,服务器提供具有内置安全控制的全面数据库管理功能:
SQL 查询执行: 执行 PostgreSQL 查询并进行风险评估
safe: 只读操作 (SELECT) - 始终允许write: 数据修改 (INSERT, UPDATE, DELETE) - 需要启用不安全模式destructive: 模式更改 (DROP, CREATE) - 需要启用不安全模式并确认SQL 解析和验证:
自动迁移版本控制:
安全控制:
asyncpg 在事务模式下运行可用工具:
get_schemas: 列出模式,包括大小和表数量get_tables: 列出表、外部表和视图及其元数据get_table_schema: 获取详细的表结构(列、键、关系)execute_postgresql: 对您的数据库执行 SQL 语句confirm_destructive_operation: 执行高风险操作前需确认retrieve_migrations: 获取迁移,并支持过滤和分页live_dangerously: 在安全模式和非安全模式之间切换从 v0.3.0 版本开始,服务器提供对 Supabase 管理 API 的安全访问,并内置安全控制:
可用工具:
send_management_api_request: 发送任意请求到 Supabase 管理 API,并自动注入项目引用get_management_api_spec: 获取增强的 API 规范,包含安全信息
get_management_api_safety_rules: 获取所有安全规则及其易于理解的解释live_dangerously: 在安全操作模式和非安全操作模式之间切换安全控制:
safe: 只读操作 (GET) - 始终允许unsafe: 修改状态的操作 (POST, PUT, PATCH, DELETE) - 需要非安全模式blocked: 破坏性操作(删除项目等) - 永不允许注意: 管理 API 工具仅适用于远程 Supabase 实例,与本地 Supabase 开发环境不兼容。
我原本计划向 MCP 服务器添加对 Python SDK 方法的支持。经过考虑,我决定只添加对 Auth 管理方法的支持,因为我经常发现自己手动创建测试用户,这容易出错且费时。现在,我可以直接请求 Cursor 创建测试用户,它会无缝完成。查看完整的 Auth 管理 SDK 方法文档以了解其功能。
从 v0.3.6 版本开始,服务器支持通过 Python SDK 直接访问 Supabase Auth 管理方法:
get_auth_admin_methods_spec 用于检索所有可用 Auth 管理方法的文档call_auth_admin_method 用于直接调用 Auth 管理方法,并进行正确的参数处理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 管理 SDK 比直接操作 SQL 提供了几个关键优势:
功能性: 支持 SQL 单独无法实现的操作(邀请、魔法链接、MFA)
准确性: 比创建和执行 auth schema 上的原始 SQL 查询更可靠
简洁性: 提供清晰的方法,并具有适当的验证和错误处理
响应格式:
user.id 而不是 user["id"])。边界情况和限制:
invite_user_by_email 和 generate_link 等方法需要在您的 Supabase 项目中配置邮件发送功能。signup 链接不需要用户存在。magiclink 和 recovery 链接要求用户已存在于系统中。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 版本开始,服务器支持:
safe 类型:始终允许。包括所有只读操作。write 类型:需要用户启用 write 模式。destructive 类型:需要用户启用 write 模式,并且对于不自动执行工具的客户端,需要进行两步确认才能执行查询。从 v0.3.8 版本开始,安全模式已在所有服务(数据库、API、SDK)中使用通用的安全管理器进行标准化。这提供了一致的风险管理和统一的界面,用于控制整个 MCP 服务器的安全设置。
所有操作(SQL 查询、API 请求、SDK 方法)都分为以下风险等级:
低 风险:不会修改数据或结构的只读操作(SELECT 查询,GET API 请求)中 风险:修改数据但不修改结构的写入操作(INSERT/UPDATE/DELETE,大多数 POST/PUT API 请求)高 风险:修改数据库结构或可能导致数据丢失的破坏性操作(DROP/TRUNCATE,DELETE API 端点)极高 风险:后果严重的、完全被阻止的操作(删除项目)安全控制基于风险等级实施:
任何高风险操作(无论是 PostgreSQL 请求还是 API 请求)即使在unsafe模式下也会被阻止。
您必须显式确认并批准每一项高风险操作才能执行。
更多详细的路线图,请查看GitHub上的这个讨论。
祝您愉快!☺️