Supabase MCP Server

查询 | 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

视窗

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

步骤1.安装

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

推荐使用pipx ，因为它为每个包创建了隔离的环境。

您还可以通过克隆存储库并从根目录运行pipx install -e .来手动安装服务器。

从源代码安装

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

通过 Smithery.ai 安装

您可以在此处找到有关如何使用 Smithery.ai 连接到此 MCP 服务器的完整说明。

步骤2.配置

Supabase MCP 服务器需要进行配置才能连接到您的 Supabase 数据库、访问 Management API 以及使用 Auth Admin SDK。本节介绍所有可用的配置选项以及如何设置它们。

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

环境变量

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

注意：默认值是为本地 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

配置方法

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

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 服务器实例：

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

选项 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 服务器并添加具有以下配置的新服务器：

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

风帆冲浪

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

如果配置正确，您应该在可用服务器列表中看到绿点指示器和可点击的 supabase 服务器。

克劳德桌面

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 桌面
   • 前往“设置”→“开发者”→“编辑配置 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 中列为可用。

克莱恩

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 服务器”选项卡
   • 点击“配置 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 服务器已连接”的消息。

故障排除

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

• 调试安装- 直接从终端运行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 上的讨论。

星史

尽情享受吧！☺️