项目简介

Self-Hosted Supabase MCP 服务器是一个遵循 Model Context Protocol (MCP) 规范的应用后端实现，专为与开发者自托管的 Supabase 实例进行交互而设计。它充当 LLM 客户端（例如 IDE 扩展）与您的本地或私有云 Supabase 项目之间的桥梁，使得您可以直接从开发环境中进行数据库自省、管理和交互。

该服务器通过实现一系列可被 LLM 客户端调用的“工具”，将复杂的 Supabase 操作转化为标准化的 MCP 请求/响应模式。

主要功能点

该服务器提供了以下核心功能，通过 MCP 工具的方式暴露给 LLM 客户端：

数据库操作: 执行 SQL 查询、查看活动连接、获取数据库统计信息。
模式与迁移: 列出数据库表、安装的扩展、已应用的迁移，并支持应用 SQL 迁移脚本。
项目配置访问: 获取项目 URL、匿名密钥和服务角色密钥（如果配置）。
开发辅助: 生成数据库模式的 TypeScript 类型定义。
认证用户管理: 列出、获取特定用户的详情，支持创建、更新和删除用户（注意：直接管理用户需要数据库连接，处理密码存在安全风险，请谨慎使用）。
存储管理: 列出存储桶和桶内的对象。
Realtime 检查: 列出 PostgreSQL 发布（通常用于 Supabase Realtime）。

安装步骤

在使用本 MCP 服务器前，请确保您的系统已安装 Node.js (推荐 18.x 或更高版本) 和 npm。

克隆仓库: 将项目代码从 GitHub 克隆到您的本地文件系统。

git clone https://github.com/HenkDz/selfhosted-supabase-mcp.git
cd selfhosted-supabase-mcp

安装依赖: 进入项目目录，安装所需的 Node.js 包。
```
npm install
```
构建项目: 编译 TypeScript 代码生成可执行的 JavaScript 文件。
```
npm run build
```
这将在 'dist' 目录下生成服务器的入口文件 'index.js'。请记住此文件的完整路径，稍后配置 MCP 客户端时需要用到。

服务器配置

本服务器需要您的 Supabase 实例的连接信息。这些信息可以通过命令行参数或环境变量提供。命令行参数优先级更高。

必须配置:
- Supabase 项目的 URL (例如 'http://localhost:8000')：对应 '--url' 参数或 'SUPABASE_URL' 环境变量。
- Supabase 项目的匿名密钥：对应 '--anon-key' 参数或 'SUPABASE_ANON_KEY' 环境变量。
可选配置 (部分功能需要):
- Supabase 服务角色密钥：对应 '--service-key' 参数或 'SUPABASE_SERVICE_ROLE_KEY' 环境变量。执行需要更高权限的操作（如自动创建 'execute_sql' 函数）时需要。
- 直接数据库连接字符串：对应 '--db-url' 参数或 'DATABASE_URL' 环境变量 (例如 'postgresql://postgres:password@localhost:5432/postgres')。执行直接访问数据库模式（如 'auth', 'storage', 'pg_catalog'）或需要事务的操作（如应用迁移、直接用户管理）时需要。
- Supabase JWT 密钥：对应 '--jwt-secret' 参数或 'SUPABASE_AUTH_JWT_SECRET' 环境变量。用于 'verify_jwt_secret' 等工具。
- 工具启用白名单文件：对应 '--tools-config <path>' 参数。一个 JSON 文件，指定允许哪些工具被 MCP 客户端调用，格式为 '{ "enabledTools": ["tool_name_1", "tool_name_2"] }'。如果未配置此参数，则默认启用所有工具。

MCP 客户端配置示例

MCP 服务器是通过 JSON-RPC 协议与 MCP 客户端（如某些 IDE 的 AI 助手或扩展）通信的。客户端通常通过启动服务器进程并与其标准输入/输出流 (stdio) 进行交互来建立连接。您需要在 MCP 客户端的配置中指定如何启动这个服务器。

以下是配置 MCP 客户端时所需的核心信息：

服务器名称: 您可以为这个服务器自定义一个名称，例如 'selfhosted-supabase'。
启动命令 (command): 启动 Node.js 进程的命令，通常是 'node'。
启动参数 (args): 传递给 Node.js 进程的参数列表。第一个参数是服务器的主文件路径 ('dist/index.js' 的完整路径)，后续参数是您的 Supabase 配置（如 '--url', '--anon-key', '--db-url' 等）。这些参数应该对应您在服务器配置中提到的命令行参数。

不同的 MCP 客户端有不同的配置方式（例如 Cursor 使用 '.cursor/mcp.json'，VS Code Copilot 使用 '.vscode/mcp.json'）。请参考您的 MCP 客户端文档，找到配置外部 MCP 服务器的部分，并按照上述 'command' 和 'args' 的结构进行配置。例如：

{
  "mcpServers": {
    "selfhosted-supabase": {
      "command": "node",
      "args": [
        "<path/to/your/selfhosted-supabase-mcp/dist/index.js>", 
        "--url", "<your-supabase-url>",
        "--anon-key", "<your-anon-key>",
        // 根据需要添加可选配置参数，例如:
        "--db-url", "<your-database-url>",
        "--service-key", "<your-service-key>"
        // 更多参数...
      ],
      // 有些客户端支持通过 env 字段传递环境变量
      "env": {
         "SUPABASE_URL": "<your-supabase-url>",
         "SUPABASE_ANON_KEY": "<your-anon-key>",
         "DATABASE_URL": "<your-database-url>",
         "SUPABASE_SERVICE_ROLE_KEY": "<your-service-key>"
         // 更多环境变量...
      }
    }
  }
}

请务必将 '<...>' 中的占位符替换为您的实际值，特别是 'dist/index.js' 文件的完整路径。出于安全考虑，敏感密钥建议通过客户端支持的环境变量方式配置，避免直接写入配置文件。

基本使用方法

一旦 MCP 客户端配置并启动了本服务器，LLM 客户端将能够发现服务器声明的工具能力。您可以通过与 LLM 助手进行对话或使用其提供的特定功能来调用这些工具。例如，您可以向助手提问“列出我的数据库表”、“执行 SQL 查询 'SELECT * FROM users LIMIT 5;'”、“帮我生成 'public' 模式的 TypeScript 类型”。LLM 客户端会识别您意图调用的工具及其所需参数，然后向 MCP 服务器发送相应的 JSON-RPC 请求。服务器执行操作后，将结果返回给 LLM 客户端，最终由客户端向您展示。

服务器运行时会将操作日志输出到标准错误流 ('stderr')，这通常对于调试很有帮助。

关键词

信息