使用说明

项目简介

Query MCP (原 Supabase MCP Server) 是一款开源工具，旨在弥合大型语言模型 (LLM) 客户端（如 Cursor、Windsurf 等 IDE）与 Supabase 后端服务之间的鸿沟。它充当一个 MCP 服务器，允许你在 IDE 中通过自然语言安全地与 Supabase 数据库、管理 API 和用户认证系统进行交互。

主要功能点

安全 SQL 查询执行： 支持在 IDE 中以自然语言执行 SQL 查询，并提供安全分级控制，防止误操作。
数据库管理： 无需离开 IDE，即可完成数据库 Schema 查看、表结构查看等管理任务。
Supabase 管理 API 集成： 通过自然语言调用 Supabase Management API，管理你的 Supabase 项目。
用户认证管理： 集成 Supabase Auth Admin SDK，方便地进行用户管理，例如创建测试用户。
兼容多种 MCP 客户端： 兼容 Cursor, Windsurf, Cline, Claude Desktop 等主流 MCP 客户端。
操作安全性控制： 提供安全、写入和破坏性三种安全级别，确保数据库操作的安全性。
自动迁移版本控制： 自动记录数据库结构变更，方便数据库版本管理。

安装步骤

环境准备： 确保你的系统已安装 Python 3.12 或更高版本。

安装 Query MCP 服务器： 使用 Python 包管理器 (pipx 或 uv) 安装 'supabase-mcp-server'。推荐使用 'pipx' 安装以创建隔离的运行环境。

# 如果已安装 pipx (推荐)
pipx install supabase-mcp-server

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

配置环境变量： Query MCP 服务器需要配置 Supabase 项目的相关信息，包括项目引用 ID、数据库密码和区域等。你可以通过以下方式配置：
- 方法一：客户端配置（推荐）： 在你的 MCP 客户端配置中直接设置环境变量（具体方法请参考客户端的使用说明）。
- 方法二：全局配置文件： 创建全局 '.env' 配置文件，该文件将用于所有 Query MCP 服务器实例。
  - macOS/Linux: '~/.config/supabase-mcp/.env'
  - Windows: '%APPDATA%\supabase-mcp.env'
  - 在 '.env' 文件中添加以下配置项，并替换为你的 Supabase 项目信息：
```
SUPABASE_PROJECT_REF=你的项目引用ID
SUPABASE_DB_PASSWORD=你的数据库密码
SUPABASE_REGION=你的项目区域 (例如: us-east-1)
SUPABASE_ACCESS_TOKEN=你的管理API访问令牌 (可选)
SUPABASE_SERVICE_ROLE_KEY=你的服务角色密钥 (可选)
```
- 方法三：项目专属配置（源码安装）： 如果你从源码安装，可以在项目根目录下创建 '.env' 文件进行配置。
查找 Supabase 项目信息：
- 项目引用 ID (Project Reference): 在 Supabase 控制台的项目 URL 中找到。
- 数据库密码 (Database Password): 在 Supabase 控制台 "Project Settings -> Database" 中查看。
- 访问令牌 (Access Token): 在 https://supabase.com/dashboard/account/tokens 生成。
- 服务角色密钥 (Service Role Key): 在 Supabase 控制台 "Project Settings -> API -> Project API keys" 中找到。

服务器配置

在 MCP 客户端（如 Cursor, Windsurf, Cline, Claude Desktop）中配置 Query MCP 服务器连接，以下是一些常用客户端的配置示例。请注意，你需要将 '<你的项目引用ID>' 和 '<你的数据库密码>' 替换为你的实际 Supabase 项目信息，'<可执行文件完整路径>' 替换为 'supabase-mcp-server' 可执行文件的完整路径（可以使用 'which supabase-mcp-server' 或 'where supabase-mcp-server' 命令查找）。

Cursor:

服务器名称 (server name): 'supabase' (可自定义)

类型 (type): 'command'

命令 (command): '<可执行文件完整路径>' (例如: '/Users/用户名/.local/bin/supabase-mcp-server' 或 'C:\Users\用户名.local\bin\supabase-mcp-server.exe')

Windsurf:

{
    "mcpServers": {
      "supabase": {
        "command": "<可执行文件完整路径>",
        "env": {
          "SUPABASE_PROJECT_REF": "<你的项目引用ID>",
          "SUPABASE_DB_PASSWORD": "<你的数据库密码>",
          "SUPABASE_REGION": "us-east-1",  // 可选，默认为 us-east-1
          "SUPABASE_ACCESS_TOKEN": "<你的管理API访问令牌>",  // 可选，用于管理 API
          "SUPABASE_SERVICE_ROLE_KEY": "<你的服务角色密钥>"   // 可选，用于 Auth Admin SDK
        }
      }
    }
}

Claude Desktop:

{
  "mcpServers": {
    "supabase": {
      "command": "<可执行文件完整路径>",
      "env": {
        "SUPABASE_PROJECT_REF": "<你的项目引用ID>",
        "SUPABASE_DB_PASSWORD": "<你的数据库密码>",
        "SUPABASE_REGION": "us-east-1",  // 可选，默认为 us-east-1
        "SUPABASE_ACCESS_TOKEN": "<你的管理API访问令牌>",  // 可选，用于管理 API
        "SUPABASE_SERVICE_ROLE_KEY": "<你的服务角色密钥>"   // 可选，用于 Auth Admin SDK
      }
    }
  }
}

Cline (VS Code 扩展):

{
  "mcpServers": {
    "supabase": {
      "command": "<可执行文件完整路径>",
      "env": {
        "SUPABASE_PROJECT_REF": "<你的项目引用ID>",
        "SUPABASE_DB_PASSWORD": "<你的数据库密码>",
        "SUPABASE_REGION": "us-east-1",  // 可选，默认为 us-east-1
        "SUPABASE_ACCESS_TOKEN": "<你的管理API访问令牌>",  // 可选，用于管理 API
        "SUPABASE_SERVICE_ROLE_KEY": "<你的服务角色密钥>"   // 可选，用于 Auth Admin SDK
      }
    }
  }
}

基本使用方法

配置完成后，在你的 MCP 客户端中，即可通过自然语言指令调用 Query MCP 服务器提供的工具，例如：

使用自然语言查询数据库表结构、数据内容。
使用自然语言执行 SQL 查询，进行数据分析和操作。
使用自然语言调用 Supabase Management API，管理你的 Supabase 项目配置。
使用自然语言调用 Supabase Auth Admin SDK，进行用户管理。

故障排除

无法连接服务器： 检查服务器启动命令是否正确，环境变量配置是否正确，以及网络连接是否正常。
工具未加载： 检查 MCP 客户端配置是否正确，服务器日志中是否有错误信息。
权限错误： 检查是否开启了 'unsafe' 模式以执行写入或破坏性操作，以及是否已进行二次确认。

更多问题和详细的故障排除指南，请参考仓库 README 文档。

关键词

使用说明

信息