使用说明

自托管Supabase MCP服务器

概述

该项目提供了模型上下文协议（MCP）专为与以下对象交互而设计的服务器 自托管的Supabase实例。它弥合了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：创建新用户（需要直接访问数据库，密码处理不安全）。
- delete_auth_user：删除用户（需要直接访问数据库）。
- update_auth_user：更新用户详细信息（需要直接访问数据库，密码处理不安全）。
存储洞察
- list_storage_buckets：列出所有存储桶。
- list_storage_objects：列出特定bucket中的对象。
实时检测
- list_realtime_publications：列出PostgreSQL出版物（通常 supabase_realtime).

（注： get_logs 最初是计划好的，但由于在自托管环境中的实现复杂性而被跳过）。

设置和安装

通过Smithery安装

通过以下方式自动安装克劳德桌面的自托管Supabase MCP服务器史密瑟里:

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

先决条件

Node.js（推荐18.x或更高版本）
npm（通常包含在Node.js中）
访问自托管的Supabase实例（URL、密钥、可能的直接DB连接字符串）。

步骤

克隆存储库：

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

安装依赖项：
```
npm install
```
构建项目：
```
npm run build
```
这将TypeScript代码编译为JavaScript dist 目录。

配置

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

重要提示：

execute_sql 辅助功能： 许多工具依赖于 public.execute_sql Supabase数据库中的函数，通过RPC安全高效地执行SQL。服务器在启动时尝试检查此功能。如果它不见了和一 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)适用于您的系统。
请谨慎将敏感密钥直接存储在配置文件中，特别是在进行版本控制的情况下。考虑在客户端支持的情况下使用环境变量或更安全的方法。

光标

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

添加以下配置：

{
  "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代码（副本）

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

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

添加以下配置：

{
  "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
      }
    }
  }
}

当您在代理模式（@workspace）下使用Copilot Chat时，它应该能检测到服务器。首次调用服务器时，系统将提示您输入详细信息（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>", 
        // 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 （节点postgres）， zod （验证）， commander （CLI参数）， @modelcontextprotocol/sdk （MCP服务器框架）。

许可证

该项目根据MIT许可证获得许可。有关详细信息，请参阅LICENSE文件。

使用说明

自托管Supabase MCP服务器

概述

目的

功能（已实现的工具）

设置和安装

通过Smithery安装

先决条件

步骤

配置

重要提示：

用法

客户端配置示例

光标

Visual Studio代码（副本）

其他客户（Windsurf、Cline、Claude）

发展

许可证

相关 MCP

Figma MCP服务器

Markdown转换服务

MCP 协议测试服务器

图像生成服务

代码安全扫描工具

网页内容抓取服务器