查询|MCP服务器的Supabase

🌅 通过pypi安装了超过17000次，在Smithery.ai上下载了近30000次——简而言之，这很有趣！ 🥳 感谢过去几个月一直使用此服务器的每个人，我希望它对您有用。自从Supabase发布了自己的官方MCP服务器, 我决定不再积极维护这个。官方MCP服务器功能丰富，还有更多未来将添加功能。来看看吧.

Query MCP is an open-source MCP server that lets your IDE safely run SQL, manage schema changes, call the Supabase Management API, and use Auth Admin SDK — all with built-in safety controls.

✨ 主要特点

💻 兼容Cursor、Windsurf、Cline等MCP客户端支持 stdio 协议
🔐 控制SQL查询执行的只读和读写模式
🔍 运行时SQL查询验证和风险级别评估
🛡️ SQL操作的三层安全系统：安全、写入和破坏
🔄 针对直接和池数据库连接的强大事务处理
📝 数据库模式更改的自动版本控制
💻 使用Suabase Management API管理您的Suabase项目
🧑‍💻 通过Python SDK使用Supabase Auth-Admin方法管理用户
🔨 预构建的工具可帮助Cursor和Windsurf更有效地与MCP配合使用
📦 通过软件包管理器（uv、pipx等）进行极其简单的安装和设置

入门指南

先决条件

安装服务器需要在系统上执行以下操作：

Python 3.12+

如果您计划通过安装 uv，确保安装.

PostgreSQL安装

MCP服务器本身不再需要安装PostgreSQL，因为它现在使用不依赖于PostgreSQL开发库的asyncpg。

但是，如果你运行的是本地Supabase实例，你仍然需要PostgreSQL：

MacOS

brew install postgresql@16

视窗

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

步骤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。配置

Suabase MCP服务器需要配置才能连接到您的Suabase数据库、访问管理API并使用Auth-Admin SDK。本节解释了所有可用的配置选项以及如何设置它们。

🔑 重要：由于v0.4 MCP服务器需要API密钥，您可以在 thequery.dev 使用此MCP服务器。

环境变量

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

变量	必填	默认	描述
`SUPABASE_PROJECT_REF`	是的	`127.0.0.1:54322`	您的Supabase项目参考ID（或本地主机：端口）
`SUPABASE_DB_PASSWORD`	是的	`postgres`	您的数据库密码
`SUPABASE_REGION`	是\*	`us-east-1`	托管Supabase项目的AWS区域
`SUPABASE_ACCESS_TOKEN`	否	无	主管管理API的个人访问令牌
`SUPABASE_SERVICE_ROLE_KEY`	否	无	身份验证管理SDK的服务角色密钥
`QUERY_API_KEY`	是	无	来自query.dev的API键（所有操作都需要）

备注：默认值是为本地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 待设置
连接到位于的主管管理API https://api.supabase.com
仅适用于远程Supabase项目（不适用于本地开发）

身份验证管理SDK连接

需要 SUPABASE_SERVICE_ROLE_KEY 待设置
对于当地发展，连接到 http://127.0.0.1:54321
对于远程项目，连接到 https://[project_ref].supabase.co

配置方法

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

环境变量：直接在您的环境中设置的值
本地 .env 文件A. .env 当前工作目录中的文件（仅在从源代码运行时有效）
全局配置文件:

- 窗户： %APPDATA%\supabase-mcp\.env - macOS/Linux： ~/.config/supabase-mcp/.env

默认设置：本地开发默认值（如果找不到其他配置）

⚠️ 重要：使用通过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"

将配置值添加到文件中：

QUERY_API_KEY=your-api-key
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/

数据库密码：在项目创建期间设置或在“项目设置”中找到→ 数据库
访问令牌：生成时间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功能仅适用于远程Suabase项目，不适用于本地开发

步骤3。用法

一般来说，任何支持以下功能的MCP客户端 stdio 协议应适用于此MCP服务器。此服务器经过明确测试，可用于：

光标
帆板运动
克莱恩
克劳德桌面

此外，您还可以使用smithery.ai为该服务器安装多个客户端，包括上述客户端。

按照以下指南在您的客户端中安装此MCP服务器。

光标

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

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

帆板运动

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

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // update path
        "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
        }
      }
    }
}

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

How successful Windsurf config looks like

克劳德桌面

Claude Desktop还通过JSON配置支持MCP服务器。按照以下步骤设置Supabase MCP服务器：

查找可执行文件的完整路径 （此步骤至关重要）：

   # On macOS/Linux
   which supabase-mcp-server

   # On Windows
   where supabase-mcp-server

复制返回的完整路径（例如。， /Users/username/.local/bin/supabase-mcp-server).

配置MCP服务器 在克劳德桌面：

- 打开克劳德桌面 - 转到“设置”→ 开发人员->编辑配置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”错误。

如果配置正确，您应该看到Claude Desktop中列出的Supabase MCP服务器可用。

How successful Windsurf config looks like

克莱恩

Cline还通过类似的JSON配置支持MCP服务器。按照以下步骤设置Supabase MCP服务器：

查找可执行文件的完整路径 （此步骤至关重要）：

   # On macOS/Linux
   which supabase-mcp-server

   # On Windows
   where supabase-mcp-server

复制返回的完整路径（例如。， /Users/username/.local/bin/supabase-mcp-server).

配置MCP服务器 在克莱恩：

- 在VS代码中打开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
         }
       }
     }
   }

如果配置正确，您应该在临床MCP服务器列表中的Supabase MCP服务器旁边看到一个绿色指示灯，并在面板底部看到一条确认“Supabase MCP-server connected”的消息。

How successful configuration in Cline looks like

故障排除

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

调试安装 -奔跑 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

环境变量 -要连接到正确的数据库，请确保在中设置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+服务器提供了全面的数据库管理功能和内置的安全控制：

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：在安全和不安全模式之间切换

API管理工具

由于v0.3.0服务器通过内置安全控件提供对Subabase Management API的安全访问：

可用工具:

- send_management_api_request：向Suabase Management API发送任意请求，并自动注入项目引用 - get_management_api_spec：获取包含安全信息的丰富的API规范 - 支持多种查询模式：按域、按特定路径/方法或所有路径 - 包括每个终点的风险评估信息 - 提供详细的参数要求和响应格式 - 帮助LLM了解主管管理API的全部功能 - get_management_api_safety_rules：获取所有具有人类可读解释的安全规则 - live_dangerously：在安全和不安全操作模式之间切换

安全控制:

- 使用与数据库操作相同的安全管理器进行一致的风险管理 - 按风险等级分类的操作： - safe：只读操作（GET）-始终允许 - unsafe：状态更改操作（POST、PUT、PATCH、DELETE）-需要不安全模式 - blocked：破坏性操作（删除项目等）-从不允许 - 默认安全模式可防止意外状态更改 - 基于路径的模式匹配，实现精确的安全规则

备注：管理API工具仅适用于远程Subabase实例，与本地Subabase开发设置不兼容。

身份验证管理工具

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

日志和分析

服务器提供对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 风险：具有严重后果的操作被完全阻止（删除项目）

根据风险等级实施安全控制：

始终允许低风险操作
中等风险操作需要启用不安全模式
高风险操作需要不安全模式和明确确认
绝不允许极端风险操作

确认流程是如何工作的

任何高风险操作（无论是postgresql还是api请求）都将被阻止，即使在 unsafe 模式。 Every high-risk operation is blocked 您必须明确确认和批准每一项高风险操作，以便执行。 Explicit approval is always required

更新日志

📦 通过包管理器简化安装-✅ （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查询验证✅ （v0.3.8）
📝 数据库更改的自动版本控制✅ （v0.3.8）
📖 api规范的知识和工具得到了根本性的改进✅ （v0.3.8）
✍️ 提高了迁移相关工具的一致性，使数据库vcs更加有序✅ （v0.3.10）
🥳 查询MCP发布（v0.4.0）

有关更详细的路线图，请参阅此讨论在GitHub上。

明星历史

![Star History Chart](https://star-history.com/#alexander-zuev/supabase-mcp-server&Date)

______________________________________________________________________

享受！ ☺️

Supabase MCP

快速接入

详细介绍