使用说明

Supabase MCP服务器

Let Cursor & Windsurf manage your Supabase and run SQL queries. Autonomously. In a safe way.

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

✨ 主要特点

💻 兼容Cursor、Windsurf、Cline等MCP客户端支持 stdio 协议
🔐 控制SQL查询执行的只读和读写模式
🔄 针对直接和池数据库连接的强大事务处理
💻 使用Suabase Management API管理您的Suabase项目
🧑‍💻 通过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

视窗

从以下网址下载并安装PostgreSQL 16+https://www.postgresql.org/download/windows/
确保在安装过程中选择了“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 安装-可编辑。从根目录。

⚠️ 如果你遇到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的任何问题，因为我还没有测试过。

通过以下方式自动安装Claude Desktop的Supabase MCP服务器史密瑟里:

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

步骤2。配置

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

本地辅助数据库实例（默认）

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

Host: 127.0.0.1:54322
Password：postgres

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

远程数据库实例

⚠️ 重要警告：不支持会话池连接，目前还没有支持它的计划。如果您觉得在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服务器：

按项目->创建 mcp.json 在您的项目/仓库文件夹中 .env 配置连接
全局->在设置中创建MCP服务器，并使用 .env 仅此MCP服务器支持

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

在仓库中创建.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"

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

窗户： %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 当前目录中的文件
全局配置文件：
- 窗户： %APPDATA%/supabase-mcp/.env
- macOS/Linux： ~/.config/supabase-mcp/.env
默认设置（本地开发）

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

一般来说，任何支持以下功能的MCP客户端 stdio 该协议应该适用于此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

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

帆板运动

转到级联->点击锤子图标->配置->填写配置：

{
    "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-mcp-server 直接从终端查看是否正常工作。如果没有，则可能是安装有问题。
MCP服务器配置 -如果上述步骤有效，则意味着服务器已正确安装和配置。只要您提供了正确的命令，IDE应该能够连接。确保提供服务器可执行文件的正确路径。
环境变量 -要连接到正确的数据库，请确保在中设置env变量 mcp_config.json 或在 .env 放置在全局配置目录中的文件(~/.config/supabase-mcp/.env 在macOS/Linux或 %APPDATA%\supabase-mcp\.env 在Windows上）。
访问日志 -MCP服务器将详细日志写入文件：
- 日志文件位置：
  - macOS/Linux： ~/.local/share/supabase-mcp/mcp_server.log
  - 窗户： %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服务器支持向Suabase Management API发送任意请求，并自动注入项目引用和安全模式控制：

包括以下工具：
- send_management_api_request 向Suabase 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 检索所有可用身份验证管理方法的文档
- 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 链接要求用户已经存在于系统中
  - 错误处理：服务器从Suabase API提供详细的错误消息，这可能与仪表板界面不同
  - 方法可用性：一些方法，如 delete_factor 在API中公开，但在SDK中未完全实现

路线图

📦 通过包管理器简化安装-✅ （v0.2.0）
🌎 支持不同的Supabase地区-✅ （v0.2.2）
🎮 通过安全控制程序访问Suabase管理API-✅ （v0.3.0）
👷‍♂️ 具有安全控制的读取和读写数据库SQL查询-✅ （v0.3.0）
🔄 针对直接连接和池连接的强大事务处理-✅ （v0.3.2）
🐍 支持原生Python SDK中可用的方法和对象-✅ （v0.3.6）
🔍 更强的SQL查询验证（读与写操作）
📝 DDL查询的自动版本控制（？）
🪵 更容易访问数据库、边缘功能日志的工具/资源（？）
👨‍💻 Supabase CLI集成（？）

连接到Supabase日志

我计划研究是否可以连接到Supabase数据库日志，这可能对调试有用（如果还不支持的话）

享受！ ☺️

使用说明

Supabase MCP服务器

目录

✨ 主要特点

入门指南

先决条件

PostgreSQL安装

步骤1。MCP服务器安装

从源代码安装

通过Smithery.ai安装

步骤2。配置

本地辅助数据库实例（默认）

远程数据库实例

光标

帆板运动

配置优先级

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

光标

帆板运动

故障排除

MCP检查员

功能概述

数据库查询工具

间接传输的实现

连接类型

API管理工具

身份验证管理工具

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

路线图

连接到Supabase日志

相关 MCP

MySQL数据库管理工具

DuckDB数据库交互服务

MongoDB 数据库 MCP 服务器

PostgreSQL管理服务器

数据库MCP工具箱

MySQL查询服务器