Self-Hosted Supabase MCP Server

セルフホスト型 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 : 新しいユーザーを作成します (直接 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 サーバーを自動的にインストールするには:

前提条件

• 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=<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 を使用してサーバーを実行します。

サーバーは標準入出力（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（コパイロット）

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. Copilot Chat をエージェントモード（@workspace）で使用すると、サーバーが検出されます。サーバーの初回起動時に、詳細情報（URL、キー、パス）の入力を求められます。

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

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

mcp.jsonまたは同等の構成ファイルを配置する場所については、各クライアントの特定のドキュメントを参照してください。

発達

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

ライセンス

このプロジェクトはMITライセンスの下で提供されています。詳細はLICENSEファイルをご覧ください。