Supabase MCP 服务器

功能丰富的 MCP 服务器，支持 Cursor 和 Windsurf 与 Supabase 数据库安全交互。它提供数据库管理、SQL 查询执行和 Supabase 管理 API 访问工具，并内置安全控制功能。

✨ 主要特点

💻 兼容 Cursor、Windsurf、Cline 和其他支持stdio协议的 MCP 客户端
🔐 控制 SQL 查询执行的只读和读写模式
🔄 针对直接和池数据库连接提供强大的事务处理
💻 使用 Supabase 管理 API 管理您的 Supabase 项目
🧑‍💻通过 Python SDK 使用 Supabase Auth Admin 方法管理用户
🔨 预建工具可帮助 Cursor & Windsurf 更有效地与 MCP 配合使用
📦通过包管理器（uv、pipx 等）进行极其简单的安装和设置

入门

先决条件

安装服务器需要您的系统具备以下条件：

Python 3.12+
PostgresSQL 16+

如果您计划通过uv安装，请确保它已安装。

PostgreSQL 安装

⚠️重要：必须在安装项目依赖项之前安装 PostgreSQL，因为 psycopg2 在编译期间需要 PostgreSQL 开发库。

MacOS

brew install postgresql@16

视窗

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

步骤 1. MCP 服务器安装

从 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 -editable . 来手动安装服务器。

⚠️ 如果您遇到 psycopg2 编译问题，则可能是缺少 PostgreSQL 开发包。请参阅上文。

从源代码安装

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

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 有关的任何问题，因为我还没有测试过它。

要通过Smithery自动为 Claude Desktop 安装 Supabase MCP 服务器：

npx -y @smithery/cli install @alexander-zuev/supabase-mcp --client claude

步骤2.配置

安装软件包后，您需要配置数据库连接设置。该服务器支持本地和远程 Supabase 实例。

本地 Supabase 实例（默认）

服务器已预先配置为使用默认设置连接到本地 Supabase 实例：

Host ：127.0.0.1:54322
Password ：postgres

💡 只要你没有修改默认设置并且想要连接到本地实例，就不需要设置环境变量。

远程 Supabase 实例

⚠️重要警告：会话池连接目前不受支持，且目前没有计划支持。如果您觉得 MCP 服务器有支持会话池连接的用例，请告知我。

对于远程 Supabase 项目，您需要配置：

SUPABASE_PROJECT_REF - 您的项目参考（可在项目 URL 中找到）
SUPABASE_DB_PASSWORD - 您的数据库密码
SUPABASE_REGION -（可选）默认为us-east-1
SUPABASE_ACCESS_TOKEN -（可选）用于管理 API 访问

您可以从项目的仪表板 URL 获取 SUPABASE_PROJECT_REF：

https://supabase.com/dashboard/project/<supabase-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 - 南美洲（圣保罗）

Cursor 和 Windsurf 的 MCP 配置方法有所不同。请阅读相关章节了解如何配置连接。

光标

自 v0.46 起，在 Cursor 中配置 MCP 服务器有两种方法：

根据项目基础 -> 在你的项目/repo 文件夹和.env中创建mcp.json来配置连接
全局 -> 在“设置”中创建一个 MCP 服务器，并使用仅受该 MCP 服务器支持的.env文件进行配置

您可以通过以下方式创建项目特定的 MCP：

如果不存在，则在您的 repo 中创建 .cursor 文件夹
使用以下设置创建或更新mcp.json文件

⚠环境变量：如果您要为每个项目配置 MCP 服务器，您仍然需要创建 .env 文件来获取连接设置。我无法配置 mcp.json 文件来获取我的环境变量 😔

{
	"mcpServers": {
	  "filesystem": {
		"command": "supabase-mcp-server",
	  }
	}
  }

或者，如果您想要全局配置 MCP 服务器（即不是针对每个项目），您可以通过运行以下命令来更新全局配置文件夹中的.env文件来配置连接设置：

# Create config directory and navigate to it
# On macOS/Linux
mkdir -p ~/.config/supabase-mcp
cd ~/.config/supabase-mcp

# On Windows (in PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp"
cd "$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"

这将打开 .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

验证文件是否存在 - 您应该看到刚刚设置的值：

# On macOS/Linux
cat ~/.config/supabase-mcp/.env

# On Windows (PowerShell)
Get-Content "$env:APPDATA\supabase-mcp\.env"

您可以找到全局配置文件：

Windows： %APPDATA%/supabase-mcp/.env
macOS/Linux： ~/.config/supabase-mcp/.env

风帆冲浪

Windsurf 支持 MCP 服务器配置的标准 .json 格式。您可以在 mcp_config.json 文件中配置服务器：

{
    "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
        }
      }
    }
}

💡查找服务器路径：
macOS/Linux：运行which supabase-mcp-server
Windows：运行where supabase-mcp-server

配置优先级

服务器按以下顺序查找配置：

环境变量（最高优先级）
当前目录中的本地.env文件
全局配置文件：
- Windows： %APPDATA%/supabase-mcp/.env
- macOS/Linux： ~/.config/supabase-mcp/.env
默认设置（本地开发）

步骤 3. 在 Cursor/Windsurf 中运行 MCP 服务器

一般来说，任何支持stdio协议的 MCP 客户端都应该可以与此 MCP 服务器（例如 Cline）配合使用，但我还没有使用除 Cursor/Windsurf 之外的任何产品对其进行测试。

光标

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

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

风帆冲浪

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

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

故障排除

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

调试安装- 直接从终端运行supabase-mcp-server看看它是否正常工作。如果不行，则安装可能有问题。
MCP 服务器配置- 如果上述步骤成功，则表示服务器已正确安装和配置。只要您输入了正确的命令，IDE 就应该能够连接。请确保提供正确的服务器可执行文件路径。
环境变量- 要连接到正确的数据库，请确保在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.0 起服务器支持只读和数据修改操作：

读取操作：用于数据检索的 SELECT 查询
数据操作语言（DML） ：用于数据更改的 INSERT、UPDATE、DELETE 操作
数据定义语言 (DDL) ：用于模式更改的 CREATE、ALTER、DROP 操作*

*注意：DDL 操作需要：

通过live_dangerously启用读写模式
连接的数据库角色具有足够的权限

交易处理

服务器支持两种执行写操作的方法：

显式事务控制（推荐）：
BEGIN; CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT); COMMIT;
单个语句：
CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);

对于 DDL 操作（CREATE/ALTER/DROP），工具描述适当地指导 Cursor/Windsurft 使用带有 BEGIN/COMMIT 块的显式事务控制。

连接类型

此 MCP 服务器使用::

直接数据库连接：连接到本地 Supabase 实例时
事务池连接：连接到远程 Supabase 实例时

通过 Supabase 的事务池连接时，某些复杂的事务模式可能无法按预期工作。对于这些环境中的架构更改，请使用显式事务块，或考虑使用 Supabase 迁移或仪表板中的 SQL 编辑器。

可用的数据库工具：

get_db_schemas - 列出所有数据库模式及其大小和表数
get_tables - 列出模式中的所有表及其大小、行数和元数据
get_table_schema - 获取详细的表结构，包括列、键和关系
execute_sql_query - 执行原始 SQL 查询，全面支持所有 PostgreSQL 操作：
- 支持所有查询类型（SELECT、INSERT、UPDATE、DELETE、CREATE、ALTER、DROP 等）
- 处理事务控制语句（BEGIN、COMMIT、ROLLBACK）
支持的模式：
- read-only - 只允许只读查询（默认模式）
- read-write - 明确启用时允许所有 SQL 操作
安全特性：
- 默认以只读模式启动
- 写入操作需要显式模式切换
- 写入操作后自动重置为只读模式
- 智能交易状态检测，防止错误
- SQL 查询验证 [TODO]

管理 API 工具

自 v0.3.0 起，服务器支持向 Supabase 管理 API 发送任意请求，并自动注入项目引用和安全模式控制：

包括以下工具：
- send_management_api_request向 Supabase Management API 发送任意请求，并自动注入项目引用和安全模式控制
- get_management_api_spec获取包含安全信息的丰富 API 规范
- get_management_api_safety_rules获取所有安全规则，包括被阻止和不安全的操作，并提供人类可读的解释
- live_dangerously在安全和不安全模式之间切换
安全特性：
- 根据操作风险，将 API 方法分为safe 、 unsafe和blocked类别
- 允许动态切换安全和不安全模式
- 无论何种模式，都不允许执行阻止操作（删除项目、删除数据库）

授权管理工具

我原本计划在 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 中完全实现

路线图

📦通过包管理器简化安装 - ✅（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 查询验证（读取与写入操作）
📝 DDL 查询的自动版本控制(?)
🪵 工具/资源可更轻松地访问数据库、边缘功能日志（？）
👨‍💻 Supabase CLI 集成（？）

连接到 Supabase 日志

我打算研究一下是否可以连接到 Supabase db 日志，这可能对调试有用（如果尚不支持的话）。

尽情享受吧！☺️

Supabase MCP Server

Integrations

Supabase MCP 服务器

目录

✨ 主要特点

入门

先决条件

PostgreSQL 安装

步骤 1. MCP 服务器安装

从源代码安装

通过 Smithery.ai 安装

步骤2.配置

本地 Supabase 实例（默认）

远程 Supabase 实例

光标

风帆冲浪

配置优先级

步骤 3. 在 Cursor/Windsurf 中运行 MCP 服务器

光标

风帆冲浪

故障排除

MCP 检查器

功能概述

数据库查询工具

交易处理

连接类型

管理 API 工具

授权管理工具

为什么使用 Auth Admin SDK 而不是原始 SQL 查询？

路线图

连接到 Supabase 日志

Appeared in Searches