自托管 Supabase MCP 服务器

概述

此项目提供了一个专为与自托管 Supabase 实例交互设计的 Model Context Protocol (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: 创建新用户（需要直接访问数据库，不安全的密码处理）。
  • delete_auth_user: 删除用户（需要直接访问数据库）。
  • update_auth_user: 更新用户详细信息（需要直接访问数据库，不安全的密码处理）。
• 存储洞察
  • list_storage_buckets: 列出所有存储桶。
  • list_storage_objects: 列出特定存储桶中的对象。
• 实时检查
  • list_realtime_publications: 列出 PostgreSQL 发布（通常是 supabase_realtime）。

(注意：get_logs 最初计划实现，但由于在自托管环境中实现复杂而被跳过。)

设置与安装

前提条件

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

步骤

1. 克隆仓库：
   bash
   git clone
   cd self-hosted-supabase-mcp

2. 安装依赖项：
   bash
   npm install

3. 构建项目：
   bash
   npm run build

   这会将 TypeScript 代码编译为 JavaScript 并存放在 dist 目录中。

配置

服务器需要您 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>: 您 Supabase 项目的 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 运行服务器，并提供必要的配置：

bash

使用命令行参数（示例）

node dist/index.js --url http://localhost:8000 --anon-key --db-url postgresql://postgres:password@localhost:5432/postgres [--service-key ]

通过配置文件进行工具白名单设置的示例

node dist/index.js --url http://localhost:8000 --anon-key --tools-config ./mcp-tools.json

或者使用环境变量配置并运行：

export SUPABASE_URL=http://localhost:8000

export SUPABASE_ANON_KEY=

export DATABASE_URL=postgresql://postgres:password@localhost:5432/postgres

export SUPABASE_SERVICE_ROLE_KEY=

如果使用了 --tools-config 选项，则必须作为命令行参数传递

node dist/index.js

使用 npm start 脚本（如果在 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. 添加如下配置：

   json
   {
   "mcpServers": {
   "selfhosted-supabase": {
   "command": "node",
   "args": [
   "<path-to-dist/index.js>", // 例如："F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js"
   "--url",
   "", // 例如："http://localhost:8000"
   "--anon-key",
   "",
   // 可选 - 如果您使用的工具需要，请添加这些
   "--service-key",
   "",
   "--db-url",
   "", // 例如："postgresql://postgres:password@host:port/postgres"
   "--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. 添加如下配置：

   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",
   // 参数通过下面设置的环境变量传递 或者对于非环境变量选项直接传递参数
   "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}",
   // ... 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}"
   // 如果缺少CLI参数，服务器会读取这些环境变量作为后备
   }
   }
   }
   }x000D

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

其他客户端（Windsurf, Cline, Claude）x000D

x000D
请参考 Cursor 或官方 Supabase 文档中显示的配置结构，并将 command 和 args 替换为此服务器的 node 命令及其参数，类似于 Cursor 示例：x000D
x000D
json_x000D_
{x000D
"mcpServers": {x000D
"selfhosted-supabase": { x000D
"command": "node",x000D
"args": [x000D
"<path-to-dist/index.js>", x000D
"--url", "", x000D
"--anon-key", "", x000D
// 可选参数...x000D
"--service-key", "", x000D
"--db-url", "", x000D
"--jwt-secret", "",x000D
// 可选工具配置_x000D_
"--tools-config", "<path-to-your-mcp-tools.json>"x000D
]x000D
}x000D
}x000D
}x000D
x000D
请查阅每个客户端的具体文档，了解应将 mcp.json 或等效配置文件放置于何处。x000D
x000D

开发_x000D_

x000D

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

许可证_x000D_

x000D
本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。