Selfhosted Supabase MCP Basic Auth

🚀 自托管Supabase MCP服务器

本项目提供了一个专门用于与自托管Supabase实例进行交互的模型上下文协议（MCP）服务器。它架起了MCP客户端（如IDE扩展）与本地或私有托管的Supabase项目之间的桥梁，让你可以直接在开发环境中进行数据库内省、管理和交互。

本服务器是从头开始构建的，借鉴了对官方Supabase云MCP服务器进行适配的经验，提供了一个专门针对自托管用例的精简、聚焦的实现。

🚀 快速开始

本项目提供的MCP服务器可让MCP客户端（如IDE扩展）与自托管的Supabase实例进行交互。以下将详细介绍其使用方法。

安装

你可以通过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、密钥，可能还需要直接的数据库连接字符串）

步骤

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 构建项目：

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

# 使用命令行参数（示例）
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 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. 添加以下配置：

{
  "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": "自托管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. 当你在代理模式（@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>", 
        // 可选参数...
        "--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或等效配置文件放置的位置。

✨ 主要特性

本服务器为使用自托管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最初有计划实现，但由于在自托管环境中的实现复杂性而被跳过。)

📚 详细文档

开发信息

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

📄 许可证

本项目采用MIT许可证。有关详细信息，请参阅LICENSE文件。