星战科技xingzhan.cloud
返回市场
自托管supabase MCP服务器

自托管supabase MCP服务器

作者：HenkDz96 星标更新：2025-07-21
安装使用来源：spider==github.com

项目介绍

自托管 Supabase MCP 服务器

License: MIT smithery badge

概述

该项目提供了一个专门为与自托管 Supabase 实例交互设计的模型上下文协议 (MCP)服务器。它弥合了MCP客户端（如IDE扩展）与您本地或私有托管的Supabase项目的差距，使您可以直接从开发环境进行数据库内省、管理和交互。

该服务器完全从零开始构建，吸取了官方Supabase云MCP服务器适应过程中的教训，提供了针对自托管用例的最小化、聚焦实现。

目的

此服务器的主要目标是让使用自托管Supabase安装的开发者能够利用基于MCP的工具来完成以下任务：

  • 查询数据库模式和数据。
  • 管理数据库迁移。
  • 查看数据库统计信息和连接。
  • 管理认证用户。
  • 与Supabase存储交互。
  • 生成类型定义。

它避免了官方云服务器在多项目管理和特定于云的API方面的复杂性，为单个项目、自托管环境提供了简化体验。

功能（已实现工具）

服务器向MCP客户端暴露以下工具：

  • 模式与迁移
    • list_tables: 列出数据库模式中的表。
    • list_extensions: 列出已安装的PostgreSQL扩展。
    • list_migrations: 列出已应用的Supabase迁移。
    • apply_migration: 应用一个SQL迁移脚本。
  • 数据库操作与统计
    • execute_sql: 执行任意SQL查询（通过RPC或直接连接）。
    • get_database_connections: 显示活动数据库连接（pg_stat_activity）。
    • get_database_stats: 获取数据库统计信息（pg_stat_*）。
  • 项目配置与密钥
    • get_project_url: 返回配置的Supabase URL。
    • get_anon_key: 返回配置的Supabase匿名密钥。
    • get_service_key: 返回配置的Supabase服务角色密钥（如果提供）。
    • verify_jwt_secret: 检查JWT密钥是否已配置并返回预览。
  • 开发与扩展工具
    • generate_typescript_types: 根据数据库模式生成TypeScript类型。
    • rebuild_hooks: 尝试重启pg_net工作者（如果使用）。
  • 认证用户管理
    • list_auth_users: 列出auth.users中的用户。
    • get_auth_user: 获取特定用户的详细信息。
    • create_auth_user: 创建新用户（需要直接DB访问，不安全的密码处理）。
    • delete_auth_user: 删除用户（需要直接DB访问）。
    • update_auth_user: 更新用户详细信息（需要直接DB访问，不安全的密码处理）。
  • 存储洞察
    • list_storage_buckets: 列出所有存储桶。
    • list_storage_objects: 列出特定桶内的对象。
  • 实时检查
    • list_realtime_publications: 列出PostgreSQL发布（通常为supabase_realtime）。

（注意：get_logs最初计划实现但因自托管环境中的实现复杂性而跳过。）

安装与设置

通过Smithery安装

要通过Smithery自动安装Self-Hosted Supabase MCP Server到Claude Desktop：

npx -y @smithery/cli install @HenkDz/selfhosted-supabase-mcp --client claude

先决条件

  • Node.js（建议使用18.x或更高版本）
  • npm（通常随Node.js一起提供）
  • 访问您的自托管Supabase实例（URL、密钥，可能还需要直接数据库连接字符串）。

步骤

  1. 克隆仓库： 
    git clone <repository-url>
cd selfhosted-supabase-mcp
  2. 安装依赖项： 
    npm install
  3. 构建项目： 
    npm run build
    这会将TypeScript代码编译到dist目录下的JavaScript中。

配置

服务器需要您的Supabase实例的配置详情。这些可以通过命令行参数或环境变量提供。命令行参数优先。

必需：

  • --url <url> 或 SUPABASE_URL=<url>: 您Supabase项目的主HTTP URL（例如，http://localhost:8000）。
  • --anon-key <key> 或 SUPABASE_ANON_KEY=<key>: 您Supabase项目的匿名密钥。

可选（但推荐/某些工具所需）：

  • --service-key <key> 或 SUPABASE_SERVICE_ROLE_KEY=<key>: 您Supabase项目的服务角色密钥。用于需要提升权限的操作，如尝试自动创建execute_sql辅助函数（如果不存在）。
  • --db-url <url> 或 DATABASE_URL=<url>: 您Supabase数据库的直接PostgreSQL连接字符串（例如，postgresql://postgres:password@localhost:5432/postgres）。对于需要直接数据库访问或事务的工具（如apply_migration、认证工具、存储工具、查询pg_catalog等）是必需的。
  • --jwt-secret <secret> 或 SUPABASE_AUTH_JWT_SECRET=<secret>: 您Supab的JWT密钥。对于verify_jwt_secret等工具是必需的。
  • --tools-config <path>: 指定启用哪些工具（白名单）的JSON文件路径。如果未指定，则启用服务器中定义的所有工具。文件应具有格式{"enabledTools": ["tool_name_1", "tool_name_2"]}。

重要提示：

  • execute_sql辅助函数： 许多工具依赖于您的Supabase数据库中的public.execute_sql函数，以通过RPC安全高效地执行SQL。服务器启动时会检查此函数是否存在。如果缺失且提供了service-key（或SUPABASE_SERVICE_ROLE_KEY）和db-url（或DATABASE_URL），则会尝试创建该函数并授予必要的权限。如果创建失败或未提供密钥，则仅依赖RPC的工具可能会失败。
  • 直接数据库访问： 与特权模式（如auth、storage）或系统目录（如pg_catalog）直接交互的工具通常需要配置DATABASE_URL以建立直接的pg连接。

使用

使用Node.js运行服务器，并提供必要的配置：

# 使用命令行参数（示例）
node dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> --db-url postgresql://postgres:password@localhost:5432/postgres [--service-key <your-service-key>]

# 示例：通过配置文件白名单工具
node dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> --tools-config ./mcp-tools.json

# 或者使用环境变量配置并运行：
# export SUPABASE_URL=http://localhost:8000
# export SUPABASE_ANON_KEY=<your-anon-key>
# export DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres
# export SUPABASE_SERVICE_ROLE_KEY=<your-service-key>
# 如果使用`--tools-config`选项，必须作为命令行参数传递
node dist/index.js

# 使用npm启动脚本（如果在package.json中配置了传递参数/读取环境变量）
npm start -- --url ... --anon-key ...

服务器通过标准输入/输出（stdio）通信，旨在由MCP客户端应用程序（如Cursor这样的IDE扩展）调用。客户端将连接到服务器的stdio流以列出和调用可用工具。

客户端配置示例

以下是配置流行MCP客户端以使用此自托管服务器的一些示例。

重要：

  • 替换占位符如<your-supabase-url>、<your-anon-key>、<your-db-url>、<path-to-dist/index.js>等，使用实际值。
  • 确保编译后的服务器文件路径（如dist/index.js）正确无误。
  • 注意不要直接在配置文件中存储敏感密钥，特别是如果提交到版本控制中。考虑使用环境变量或客户端支持的安全方法。

Cursor

  1. 在项目根目录下创建或打开.cursor/mcp.json文件。

  2. 添加以下配置：

    {
  "mcpServers": {
    "selfhosted-supabase": { 
      "command": "node",
      "args": [
        "<path-to-dist/index.js>", // 例如："F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js"
        "--url",
        "<your-supabase-url>", // 例如："http://localhost:8000"
        "--anon-key",
        "<your-anon-key>",
        // 可选 - 如果使用的工具需要，请添加这些
        "--service-key",
        "<your-service-key>",
        "--db-url",
        "<your-db-url>", // 例如："postgresql://postgres:password@host:port/postgres"
        "--jwt-secret",
        "<your-jwt-secret>",
        // 可选 - 白名单特定工具
        "--tools-config",
        "<path-to-your-mcp-tools.json>" // 例如："./mcp-tools.json"
      ]
    }
  }
}

Visual Studio Code (Copilot)

VS Code Copilot允许使用通过提示输入填充的环境变量，这更安全地处理密钥。

  1. 在项目根目录下创建或打开.vscode/mcp.json文件。

  2. 添加以下配置：

    {
  "inputs": [
    { "type": "promptString", "id": "sh-supabase-url", "description": "自托管Supabase URL", "default": "http://localhost:8000" },
    { "type": "promptString", "id": "sh-supabase-anon-key", "description": "自托管Supabase匿名密钥", "password": true },
    { "type": "promptString", "id": "sh-supabase-service-key", "description": "自托管Supabase服务密钥（可选）", "password": true, "required": false },
    { "type": "promptString", "id": "sh-supabase-db-url", "description": "自托管Supabase数据库URL（可选）", "password": true, "required":  false },
    { "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "自托管Supabase JWT密钥（可选）", "password": true, "required": false },
    { "type": "promptString", "id": "sh-supabase-server-path", "description": "到self-hosted-supabase-mcp/dist/index.js的路径" },
    { "type": "promptString", "id": "sh-supabase-tools-config", "description": "到工具配置JSON的路径（可选，例如：./mcp-tools.json）", "required": false }
  ],
  "servers": {
    "selfhosted-supabase": {
      "command": "node",
      // 参数通过下面设置的环境变量传递，或者直接传递非环境选项
      "args": [
        "${input:sh-supabase-server-path}",
        // 对于无法直接映射到标准环境变量的选项（如tools-config），使用直接参数
        // 在添加参数之前检查tools-config输入是否提供
        ["--tools-config", "${input:sh-supabase-tools-config}"]
        // 或者如果更简单，全部作为参数传递：
        // "--url", "${input:sh-supabase-url}",
        // "--anon-key", "${input:sh-supabase-anon-key}",
        // ...等等...
       ],
      "env": {
        "SUPABASE_URL": "${input:sh-supabase-url}",
        "SUPABASE_ANON_KEY": "${input:sh-supabase-anon-key}",
        "SUPABASE_SERVICE_ROLE_KEY": "${input:sh-supabase-service-key}",
        "DATABASE_URL": "${input:sh-supabase-db-url}",
        "SUPABASE_AUTH_JWT_SECRET": "${input:sh-supabase-jwt-secret}"
        // 如果缺少命令行参数，服务器将读取这些环境变量作为后备
      }
    }
  }
}

  3. 当您首次使用Copilot Chat在Agent模式（@workspace）时，它应该检测到服务器。当首次调用服务器时，您将被提示输入详细信息（URL、密钥、路径）。

其他客户端（Windsurf、Cline、Claude）

根据Cursor或官方Supabase文档所示的配置结构进行调整，替换command和args为node命令和此服务器的参数，类似于Cursor示例：

{
  "mcpServers": {
    "selfhosted-supabase": { 
      "command": "node",
      "args": [
        "<path-to-dist/index.js>", 
        "--url", "<your-supabase-url>", 
        "--anon-key", "<your-anon-key>", 
        // 可选参数...
        "--service-key", "<your-service-key>", 
        "--db-url", "<your-db-url>", 
        "--jwt-secret", "<your-jwt-secret>",
        // 可选工具配置
        "--tools-config", "<path-to-your-mcp-tools.json>"
      ]
    }
  }
}

查阅每个客户端的具体文档，了解在哪里放置mcp.json或等效配置文件。

开发

  • 语言： TypeScript
  • 构建： tsc（TypeScript 编译器）
  • 依赖项： 通过npm（package.json）管理
  • 核心库： @supabase/supabase-js，pg（node-postgres），zod（验证），commander（CLI参数），@modelcontextprotocol/sdk（MCP服务器框架）。

许可证

本项目采用MIT许可证。详情见LICENSE文件。