Skip to main content
Glama
deenesjakoruzh
HenkDz

Self-Hosted Supabase MCP Server

by HenkDz
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

自托管 Supabase MCP 服务器

许可证：MIT 铁匠徽章

概述

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

该服务器是从头开始构建的，借鉴了官方 Supabase 云 MCP 服务器的经验教训，以提供针对自托管用例量身定制的最小、集中的实现。

Related MCP server: 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 ：创建新用户（需要直接数据库访问，不安全的密码处理）。

    • delete_auth_user ：删除用户（需要直接数据库访问）。

    • update_auth_user ：更新用户详细信息（需要直接数据库访问，不安全的密码处理）。

  • 存储洞察

    • list_storage_buckets ：列出所有存储桶。

    • list_storage_objects ：列出特定存储桶内的对象。

  • 实时检查

    • list_realtime_publications ：列出 PostgreSQL 出版物（通常是supabase_realtime ）。

（注意：最初计划使用

设置和安装

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装自托管 Supabase MCP 服务器：

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

先决条件

  • Node.js（建议使用 18.x 或更高版本）

  • npm（通常包含在 Node.js 中）

  • 访问您自托管的 Supabase 实例（URL、密钥、潜在的直接 DB 连接字符串）。

步骤

  1. 克隆存储库：

    git clone <repository-url>
cd self-hosted-supabase-mcp

  2. 安装依赖项：

    npm install

  3. 构建项目：

    npm run build

    这会将dist目录中的 TypeScript 代码编译为 JavaScript。

配置

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

必需的：

  • --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> ：你的 Supabase 项目的 JWT 密钥。verify_jwt_secret verify_jwt_secret工具需要用到。

  • --tools-config <path> ：指定要启用哪些工具（白名单）的 JSON 文件路径。如果省略，则启用服务器中定义的所有工具。该文件的格式应为{"enabledTools": ["tool_name_1", "tool_name_2"]} 。

重要提示：

  • **execute_sql辅助函数：许多工具依赖于 Supabase 数据库中的提供了service-key （或SUPABASE_SERVICE_ROLE_KEY ）和db-url （或DATABASE_URL ），它将尝试创建该函数并授予必要的权限。如果创建失败或未提供密钥，则仅依赖 RPC 的工具可能会失败。

  • **直接数据库访问：**直接与特权模式（ auth 、 storage ）或系统目录（ pg_catalog ）交互的工具通常需要配置DATABASE_URL以进行直接pg连接。

用法

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

# Using CLI arguments (example)
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>]

# Example with tool whitelisting via config file
node dist/index.js --url http://localhost:8000 --anon-key <your-anon-key> --tools-config ./mcp-tools.json

# Or configure using environment variables and run:
# 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>
# The --tools-config option MUST be passed as a CLI argument if used
node dist/index.js

# Using npm start script (if configured in package.json to pass args/read env)
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 ）的路径对于您的系统来说是正确的。

  • 请谨慎将敏感密钥直接存储在配置文件中，尤其是在已提交版本控制的情况下。请考虑使用环境变量或客户端支持的更安全的方法。

光标

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

  2. 添加以下配置：

    {
  "mcpServers": {
    "selfhosted-supabase": { 
      "command": "node",
      "args": [
        "<path-to-dist/index.js>", // e.g., "F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js"
        "--url",
        "<your-supabase-url>", // e.g., "http://localhost:8000"
        "--anon-key",
        "<your-anon-key>",
        // Optional - Add these if needed by the tools you use
        "--service-key",
        "<your-service-key>",
        "--db-url",
        "<your-db-url>", // e.g., "postgresql://postgres:password@host:port/postgres"
        "--jwt-secret",
        "<your-jwt-secret>",
        // Optional - Whitelist specific tools
        "--tools-config",
        "<path-to-your-mcp-tools.json>" // e.g., "./mcp-tools.json"
      ]
    }
  }
}

Visual Studio Code（Copilot）

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

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

  2. 添加以下配置：

    {
  "inputs": [
    { "type": "promptString", "id": "sh-supabase-url", "description": "Self-Hosted Supabase URL", "default": "http://localhost:8000" },
    { "type": "promptString", "id": "sh-supabase-anon-key", "description": "Self-Hosted Supabase Anon Key", "password": true },
    { "type": "promptString", "id": "sh-supabase-service-key", "description": "Self-Hosted Supabase Service Key (Optional)", "password": true, "required": false },
    { "type": "promptString", "id": "sh-supabase-db-url", "description": "Self-Hosted Supabase DB URL (Optional)", "password": true, "required": false },
    { "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "Self-Hosted Supabase JWT Secret (Optional)", "password": true, "required": false },
    { "type": "promptString", "id": "sh-supabase-server-path", "description": "Path to self-hosted-supabase-mcp/dist/index.js" },
    { "type": "promptString", "id": "sh-supabase-tools-config", "description": "Path to tools config JSON (Optional, e.g., ./mcp-tools.json)", "required": false }
  ],
  "servers": {
    "selfhosted-supabase": {
      "command": "node",
      // Arguments are passed via environment variables set below OR direct args for non-env options
      "args": [
        "${input:sh-supabase-server-path}",
        // Use direct args for options not easily map-able to standard env vars like tools-config
        // Check if tools-config input is provided before adding the argument
        ["--tools-config", "${input:sh-supabase-tools-config}"] 
        // Alternatively, pass all as args if simpler:
        // "--url", "${input:sh-supabase-url}",
        // "--anon-key", "${input:sh-supabase-anon-key}",
        // ... etc ... 
       ],
      "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}"
        // The server reads these environment variables as fallbacks if CLI args are missing
      }
    }
  }
}

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

其他客户（Windsurf、Cline、Claude）

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

{
  "mcpServers": {
    "selfhosted-supabase": { 
      "command": "node",
      "args": [
        "<path-to-dist/index.js>", 
        "--url", "<your-supabase-url>", 
        "--anon-key", "<your-anon-key>", 
        // Optional args...
        "--service-key", "<your-service-key>", 
        "--db-url", "<your-db-url>", 
        "--jwt-secret", "<your-jwt-secret>",
        // Optional tools config
        "--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 文件。

Install Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/HenkDz/selfhosted-supabase-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server