自托管 Supabase MCP 服务器

概述

该项目提供了一个专为与自托管 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 ：创建新用户（需要直接数据库访问，不安全的密码处理）。

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

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

• 存储洞察

  • list_storage_buckets ：列出所有存储桶。

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

• 实时检查

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

（注意：最初计划使用

设置和安装

通过 Smithery 安装

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

先决条件

• 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 运行服务器，提供必要的配置：

该服务器通过标准输入/输出 (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 示例：

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

发展

• 语言： TypeScript

• 构建： tsc （TypeScript 编译器）

• **依赖项：**通过npm管理（ package.json ）

• 核心库： @supabase/supabase-js 、 pg （node-postgres）、 zod （验证）、 commander （CLI 参数）、 @modelcontextprotocol/sdk （MCP 服务器框架）。

执照

本项目遵循 MIT 许可证。详情请参阅 LICENSE 文件。