MCP 服务器

Supabase MCP Server
精选

通过提供数据库管理、SQL查询执行和Supabase管理API访问工具，并内置安全控制，使Cursor和Windsurf能够安全地与Supabase数据库交互。

远程shell执行

数据库交互

数据与应用分析

访问服务器

README

Supabase MCP 服务器

让 Cursor & Windsurf 管理你的 Supabase 并运行 SQL 查询。自主地。以安全的方式。

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

✨ 主要功能

💻 兼容 Cursor、Windsurf、Cline 和其他支持 stdio 协议的 MCP 客户端
🔐 控制 SQL 查询执行的只读和读写模式
🔄 针对直接和池化数据库连接的强大事务处理
💻 使用 Supabase Management 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

Windows

从 https://www.postgresql.org/download/windows/ 下载并安装 PostgreSQL 16+
确保在安装过程中选择“PostgreSQL Server”和“Command Line Tools”

步骤 1. MCP 服务器安装

自 v0.2.0 起，我引入了对包安装的支持。您可以使用您喜欢的 Python 包管理器通过以下方式安装服务器：

# 如果已安装 pipx（推荐）
pipx install supabase-mcp-server

# 如果已安装 uv
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 Server：

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 - （可选）用于 Management 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 - 南美洲（圣保罗）

MCP 配置方法在 Cursor 和 Windsurf 之间有所不同。阅读相关部分以了解如何配置连接。

Cursor

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

基于每个项目 -> 在您的项目/存储库文件夹中创建 mcp.json 和 .env 以配置连接
全局 -> 在设置中创建一个 MCP 服务器，并使用 .env 进行配置，该 .env 仅由此 MCP 服务器支持

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

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

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

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

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

# 创建配置目录并导航到该目录
# 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"

这将创建必要的配置文件夹，您的环境文件将存储在该文件夹中。

# 创建并编辑 .env 文件
# 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

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 以外的任何东西进行测试。

Cursor

转到 Settings -> Features -> MCP Servers 并添加一个具有以下配置的新服务器：

# 可以设置为任何名称
name: supabase
type: command
# 如果您使用 pipx 安装
command: supabase-mcp-server
# 如果您使用 uv 安装
command: uv run supabase-mcp-server

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

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

How successful Windsurf config looks like

问题排查

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

调试安装 - 直接从终端运行 supabase-mcp-server 以查看它是否有效。如果它不起作用，则安装可能存在问题。
MCP 服务器配置 - 如果上述步骤有效，则表示服务器已正确安装和配置。只要您提供了正确的命令，IDE 应该能够连接。确保提供服务器可执行文件的正确路径。
环境变量 - 要连接到正确的数据库，请确保您在 mcp_config.json 中或放置在全局配置目录中的 .env 文件中设置了 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 检查器是一个非常有用的工具，可以帮助调试 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]

Management API 工具

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

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

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

Auth Admin SDK 提供了优于直接 SQL 操作的几个关键优势：

功能：启用仅使用 SQL 无法实现的操作（邀请、魔法链接、MFA）
准确性：比在 auth 模式上创建和执行原始 SQL 查询更可靠
简单性：提供具有正确验证和错误处理的清晰方法
- 响应格式：
  - 所有方法都返回结构化的 Python 对象而不是原始字典
  - 可以使用点表示法访问对象属性（例如，user.id 而不是 user["id"]）
- 边缘情况和限制：
  - UUID 验证：许多方法需要有效的 UUID 格式的用户 ID，并将返回特定的验证错误
  - 电子邮件配置：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 精选

README

Supabase MCP 服务器

目录

✨ 主要功能

开始使用

前提条件

PostgreSQL 安装

步骤 1. MCP 服务器安装

从源代码安装

通过 Smithery.ai 安装

步骤 2. 配置

本地 Supabase 实例（默认）

远程 Supabase 实例

Cursor

Windsurf

配置优先级

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

Cursor

Windsurf

问题排查

MCP 检查器

功能概述

数据库查询工具

事务处理

连接类型

Management API 工具

Auth Admin 工具

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

路线图

连接到 Supabase 日志

推荐服务器

Supabase MCP Server
精选