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文件。