Selfhosted Supabase MCP Basic Auth

🚀 セルフホスト型Supabase MCPサーバー

このプロジェクトは、セルフホスト型Supabaseインスタンスとのやり取りを目的としたモデルコンテキストプロトコル (MCP)サーバーを提供します。これにより、MCPクライアント（IDE拡張機能など）とローカルまたはプライベートでホストされたSupabaseプロジェクトの間のギャップを埋め、開発環境から直接データベースのイントロスペクション、管理、およびインタラクションが可能になります。

このサーバーは、公式のSupabaseクラウドMCPサーバーを適応させる過程で得た教訓を活かしてゼロから構築され、セルフホストのユースケースに特化した最小限で焦点を絞った実装を提供します。

🚀 クイックスタート

このセルフホスト型Supabase MCPサーバーを使用することで、セルフホストのSupabaseインスタンスとMCPクライアントの間のやり取りが可能になります。以下のセクションでは、サーバーのセットアップ、構成、使用方法について説明します。

✨ 主な機能

このサーバーは、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: 新しいユーザーを作成します（直接のDBアクセスが必要で、パスワードの取り扱いが安全ではありません）。
• delete_auth_user: ユーザーを削除します（直接のDBアクセスが必要です）。
• update_auth_user: ユーザーの詳細を更新します（直接のDBアクセスが必要で、パスワードの取り扱いが安全ではありません）。

ストレージインサイト

• list_storage_buckets: すべてのストレージバケットを一覧表示します。
• list_storage_objects: 特定のバケット内のオブジェクトを一覧表示します。

リアルタイムインスペクション

• list_realtime_publications: PostgreSQLのパブリケーションを一覧表示します（多くの場合supabase_realtime）。

（注: get_logsは当初計画されていましたが、セルフホスト環境での実装が複雑であるためスキップされました。）

📦 インストール

Smitheryを介したインストール

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、キー、場合によっては直接のDB接続文字列）

手順

1. リポジトリをクローンします。

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

2. 依存関係をインストールします。

   npm install
   

3. プロジェクトをビルドします。

   npm run build
   

   これにより、TypeScriptコードがdistディレクトリに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=: 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ヘルパー関数: 多くのツールは、RPCを介した安全で効率的なSQL実行のために、Supabaseデータベース内のpublic.execute_sql関数に依存しています。サーバーは起動時にこの関数をチェックしようとします。関数が欠落している場合、かつservice-key（またはSUPABASE_SERVICE_ROLE_KEY）とdb-url（またはDATABASE_URL）が提供されている場合、関数を作成し、必要な権限を付与しようとします。作成に失敗した場合、またはキーが提供されていない場合、RPCのみに依存するツールは失敗する可能性があります。
• 直接のデータベースアクセス: 特権付きスキーマ（auth、storage）またはシステムカタログ（pg_catalog）と直接やり取りするツールは、一般に、直接のpg接続のためにDATABASE_URLを構成する必要があります。

使用方法

必要な構成を指定して、Node.jsを使用してサーバーを実行します。

# CLI引数を使用する場合（例）
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オプションは、使用する場合はCLI引数として渡す必要があります。
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": "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}",
        // ... など ... 
      ],
      "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引数が欠落している場合、これらの環境変数をフォールバックとして読み取ります。
      }
    }
  }
}

3. Copilot Chatをエージェントモード（@workspace）で使用すると、サーバーが検出されます。サーバーが最初に呼び出されたときに、詳細（URL、キー、パス）を入力するように促されます。

その他のクライアント（Windsurf、Cline、Claude）

Cursorの例と同様に、Cursorまたは公式のSupabaseドキュメントに示されている構成構造を適応させ、commandとargsをこのサーバーのnodeコマンドと引数に置き換えます。

{
  "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または同等の構成ファイルを配置する場所を確認してください。

開発

• 言語: TypeScript
• ビルド: tsc (TypeScriptコンパイラ)
• 依存関係: npm (package.json)を介して管理
• コアライブラリ: @supabase/supabase-js、pg (node-postgres)、zod (バリデーション)、commander (CLI引数)、@modelcontextprotocol/sdk (MCPサーバーフレームワーク)

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。