Supabase MCP Server

Supabase MCP 服务

  

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

这是一款功能丰富的 MCP 服务，可让任何 MCP 客户端（Cursor、Windsurf、Claude Desktop、Cline 等）安全地与 Supabase 数据库交互。它提供数据库管理、SQL 查询执行和 Supabase Management API 访问工具，并内置安全控制。

目录

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

✨ 主要功能

• 💻 兼容 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。本节将介绍所有可用的配置选项以及设置方法。

环境变量

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

变量	必需	默认值	说明
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 Management API 的个人访问令牌
SUPABASE_SERVICE_ROLE_KEY	否	None	用于 Auth Admin SDK 的服务角色密钥

注意：默认值是为本地 Supabase 开发配置的。对于远程 Supabase 项目，你必须为 SUPABASE_PROJECT_REF 和 SUPABASE_DB_PASSWORD 提供自己的值。

连接类型

数据库连接

• 服务使用事务池化端点连接到你的 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"

将配置值添加到文件中：

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": {
          "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": {
           "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": {
           "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 中完整实现

数据库更改的自动版本控制

“能力越大，责任越大。”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）

如需查看更详细的路线图，请参阅 GitHub 上的这篇讨论。

连接到 Supabase 日志

我计划研究是否可以连接到 Supabase 数据库日志，这可能有助于调试（如果目前尚未支持的话）。

---

祝使用愉快！☺️