技术文档摘要

Query | MCP服务器用于Supabase

🌅 通过pypi安装超过17000次，在Smithery.ai上接近30000次下载——总之，这很有趣！ 🥳 感谢过去几个月使用此服务器的每个人，希望它对你有用。 由于Supabase已经发布了他们自己的官方MCP服务器，我决定不再积极维护这个版本。官方MCP服务器功能丰富，并且未来会添加更多功能。请查看！

<p class="center-text"> <strong>Query MCP是一个开源的MCP服务器，允许你的IDE安全地运行SQL、管理模式更改、调用Supabase管理API以及使用Auth Admin SDK——所有这些都内置了安全控制。</strong> </p> <p class="center-text"> <a href="https://pypi.org/project/supabase-mcp-server/"><img src="https://img.shields.io/pypi/v/supabase-mcp-server.svg" alt="PyPI版本" /></a> <a href="https://github.com/alexander-zuev/supabase-mcp-server/actions"><img src="https://github.com/alexander-zuev/supabase-mcp-server/workflows/CI/badge.svg" alt="CI状态" /></a> <a href="https://codecov.io/gh/alexander-zuev/supabase-mcp-server"><img src="https://codecov.io/gh/alexander-zuev/supabase-mcp-server/branch/main/graph/badge.svg" alt="代码覆盖率" /></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg" alt="Python 3.12+" /></a> <a href="https://github.com/astral-sh/uv"><img src="https://img.shields.io/badge/uv-包管理器-blueviolet" alt="uv包管理器" /></a> <a href="https://pepy.tech/project/supabase-mcp-server"><img src="https://static.pepy.tech/badge/supabase-mcp-server" alt="PyPI下载量" /></a> <a href="https://smithery.ai/server/@alexander-zuev/supabase-mcp-server"><img src="https://smithery.ai/badge/@alexander-zuev/supabase-mcp-server" alt="Smithery.ai下载量" /></a> <a href="https://modelcontextprotocol.io/introduction"><img src="https://img.shields.io/badge/MCP-服务器-orange" alt="MCP服务器" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="许可证" /></a> </p>

目录

<p class="center-text"> <a href="#getting-started">开始使用</a> • <a href="#feature-overview">功能概述</a> • <a href="#troubleshooting">故障排除</a> • <a href="#changelog">更新日志</a> </p>

✨ 关键特性

• 💻 兼容Cursor、Windsurf、Cline和其他支持stdio协议的MCP客户端
• 🔐 控制SQL查询执行的只读和读写模式
• 🔍 运行时SQL查询验证及风险级别评估
• 🛡️ 三层安全系统用于SQL操作：安全、写入和破坏性
• 🔄 坚固的事务处理，适用于直接和池化数据库连接
• 📝 数据库模式更改的自动版本控制
• 💻 使用Supabase管理API管理Supabase项目
• 🧑‍💻 使用Supabase Auth Admin方法管理用户（通过Python SDK）
• 🔨 预构建工具帮助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”和“命令行工具”

第一步：安装

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

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

# 如果已安装uv
uv pip install supabase-mcp-server

推荐使用pipx，因为它为每个包创建隔离环境。

您也可以通过克隆仓库并从根目录运行pipx install -e .来手动安装服务器。

从源码安装

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

uv venv
# 在Mac上
source .venv/bin/activate
# 在Windows上
.venv\Scripts\activate
# 以可编辑模式安装包
uv pip install -e .

通过Smithery.ai安装

有关如何使用Smithery.ai连接到此MCP服务器的完整说明，请参阅这里。

第二步：配置

Supabase MCP服务器需要配置以连接到您的Supabase数据库、访问管理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	否	无	Supabase管理API的个人访问令牌
SUPABASE_SERVICE_ROLE_KEY	否	无	Auth Admin SDK的服务角色密钥
QUERY_API_KEY	是	无	从thequery.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
• 连接到Supabase管理API的https://api.supabase.com
• 仅适用于远程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服务器实例：

# 创建配置目录
# 在macOS/Linux上
mkdir -p ~/.config/supabase-mcp
# 在Windows（PowerShell）上
mkdir -Force "$env:APPDATA\supabase-mcp"

# 创建并编辑.env文件
# 在macOS/Linux上
nano ~/.config/supabase-mcp/.env
# 在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/<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项目，不适用于本地开发

第三步：使用

一般来说，任何支持stdio协议的MCP客户端都应该能与这个MCP服务器一起工作。此服务器经过测试，可以与以下客户端一起工作：

• Cursor
• Windsurf
• Cline
• Claude Desktop

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

请遵循下面的指南在您的客户端中安装此MCP服务器。

Cursor

前往设置 -> 功能 -> MCP服务器并添加一个新的服务器配置：

# 可以设置为任意名称
name: supabase
type: command
# 如果您使用pipx安装
command: supabase-mcp-server
# 如果您使用uv安装
command: uv run supabase-mcp-server
# 如果上面的方法不起作用，请使用完整路径（推荐）
command: /full/path/to/supabase-mcp-server  # 使用'which supabase-mcp-server'（macOS/Linux）或'where supabase-mcp-server'（Windows）找到

如果配置正确，您应该看到绿色指示灯，并显示服务器提供的工具数量。

Windsurf

前往Cascade -> 点击锤子图标 -> 配置 -> 填写配置：

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // 更新路径
        "env": {
          "QUERY_API_KEY": "your-api-key",  // 必需 - 在thequery.dev获取您的API密钥
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // 可选，默认为us-east-1
          "SUPABASE_ACCESS_TOKEN": "your-access-token",  // 可选，用于管理API
          "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // 可选，用于Auth Admin SDK
        }
      }
    }
}

如果配置正确，您应该看到绿色指示灯，并且在可用服务器列表中可以看到可点击的Supabase服务器。

Claude Desktop

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

1. 找到可执行文件的完整路径（这一步至关重要）：

   # 在macOS/Linux上
   which supabase-mcp-server
   
   # 在Windows上
   where supabase-mcp-server
   

   复制返回的实际路径（例如，/Users/username/.local/bin/supabase-mcp-server）。

2. 在Claude Desktop中配置MCP服务器：

   • 打开Claude Desktop
   • 前往设置 → 开发者 -> 编辑配置MCP服务器
   • 添加以下JSON配置：

   {
     "mcpServers": {
       "supabase": {
         "command": "/full/path/to/supabase-mcp-server",  // 替换为步骤1中的实际路径
         "env": {
           "QUERY_API_KEY": "your-api-key",  // 必需 - 在thequery.dev获取您的API密钥
           "SUPABASE_PROJECT_REF": "your-project-ref",
           "SUPABASE_DB_PASSWORD": "your-db-password",
           "SUPABASE_REGION": "us-east-1",  // 可选，默认为us-east-1
           "SUPABASE_ACCESS_TOKEN": "your-access-token",  // 可选，用于管理API
           "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"  // 可选，用于Auth Admin SDK
         }
       }
     }
   }
   

⚠️ 重要：与Windsurf和Cursor不同，Claude Desktop需要可执行文件的完整绝对路径。仅使用命令名（supabase-mcp-server）会导致“spawn ENOENT”错误。

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

Cline

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

1. 找到可执行文件的完整路径（这一步至关重要）：

   # 在macOS/Linux上
   which supabase-m