Supabase Coolify Mcp Server

Supabase Coolify MCP サーバー

⚡ ワンクリックインストール

お好みのAIコーディングツールに直接インストールできます。

Claude Code:

claude mcp add supabase-coolify -- npx -y supabase-coolify-mcp-server

Note: インストール後、必須の環境変数を設定する必要があります。以下の設定を参照してください。

---

Coolify 上のセルフホスト型 Supabase を管理するための、包括的な TypeScript 製 MCP（Model Context Protocol）サーバーです。このサーバーを使うと、AI エージェントはマイグレーションの完全なデプロイ、エッジ関数のプッシュ、サービスの設定、Supabase デプロイの管理を簡単に行えます。

📦 NPM パッケージ • 📚 ドキュメント • 🚀 クイックスタート

🚀 機能

Supabase の管理

• データベースマイグレーション：データベースマイグレーションのデプロイ、追跡、ロールバック、管理
• マイグレーションのロールバック：down SQL に対応し、安全にマイグレーションをロールバック
• Supabase CLI との統合：ローカル開発とデプロイのための完全な CLI 統合
• エッジ関数：エッジ関数のデプロイ、呼び出し、監視、削除
• ストレージ管理：ストレージバケットの作成と管理
• 認証設定：認証プロバイダーと設定を構成
• リアルタイム設定：リアルタイムサービスの設定を管理
• ヘルスモニタリング：すべての Supabase サービスの状態を確認
• 型生成：データベーススキーマから TypeScript の型を生成

本番環境向け機能

• 入力検証：すべてのツール入力を Zod で検証
• ヘルスチェック：起動時の自動チェックと確認ツール
• エラー処理：トラブルシューティングのヒントを含む包括的なエラーメッセージ
• 型安全性：全体で完全な TypeScript サポート

Coolify との統合

• アプリケーション管理：アプリケーションの一覧表示、デプロイ、起動、停止、再起動
• サービス管理：Coolify サービスを制御
• データベース管理：Coolify 上でホストされているデータベースを管理
• 環境変数：アプリケーションの設定を安全に更新
• ログ：デバッグ用にアプリケーションログにアクセス

デプロイの自動化

• ワンクリックデプロイ：Coolify 上に Supabase インスタンス一式をデプロイ
• 設定管理：デプロイ設定を動的に更新
• 状態モニタリング：デプロイの健全性と状態を追跡

📋 前提条件

• Node.js >= 18.0.0
• Coolify インスタンス（セルフホストまたはクラウド）
• 適切な権限を持つ Coolify API トークン
• セルフホスト型 Supabase インスタンス（またはデプロイする準備）

🔧 インストール

方法 1：NPM（推奨）

NPM 経由でグローバルにインストールします：

npm install -g supabase-coolify-mcp-server

または、npx で直接使用します（インストール不要）：

npx supabase-coolify-mcp-server

パッケージ： https://www.npmjs.com/package/supabase-coolify-mcp-server

方法 2：ソースから

GitHub からクローンしてビルドします：

git clone https://github.com/dj-pearson/supabase-coolify-mcp-server.git
cd supabase-coolify-mcp-server
npm install
npm run build

⚙️ 設定

環境変数

.env ファイルを作成するか、以下の環境変数を設定します：

# Required: Coolify Configuration
COOLIFY_API_URL=http://localhost:8000
COOLIFY_API_TOKEN=your-coolify-api-token-here

# Required: Supabase Configuration
SUPABASE_URL=https://your-supabase-instance.example.com
SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

# Optional: Coolify Team
COOLIFY_TEAM_ID=optional-team-id

# Optional: Supabase Additional Config
SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_PROJECT_ID=your-project-id
SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_FUNCTIONS_URL=https://your-supabase-instance.example.com/functions/v1

# Optional: Direct Database Access
SUPABASE_DB_HOST=localhost
SUPABASE_DB_PORT=5432
SUPABASE_DB_NAME=postgres
SUPABASE_DB_USER=postgres
SUPABASE_DB_PASSWORD=your-db-password

API トークンの取得

Coolify API トークン

1. Coolify インスタンスにログインします
2. 「Keys & Tokens」>「API tokens」に移動します
3. 「Create New Token」をクリックします
4. 権限を選択します（推奨：フルアクセスの場合は *）
5. 生成されたトークンをコピーします

Supabase サービスロールキー

セルフホストの Supabase の場合：

1. Supabase ダッシュボードにログインします
2. Settings > API に移動します
3. service_role キーをコピーします（安全に保管してください！）

または、Supabase のデプロイ環境変数から取得します：

echo $SERVICE_ROLE_KEY

🎯 使用方法

⚠️ 重要：環境変数が必要です

MCP サーバーが Coolify と Supabase に接続するには、環境変数が必要です。

推奨設定（すべてのユーザーに適しています）：

環境変数を MCP 設定に直接追加します：

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "npx",
      "args": ["-y", "supabase-coolify-mcp-server"],
      "env": {
        "COOLIFY_API_URL": "http://your-coolify-url:8000",
        "COOLIFY_API_TOKEN": "your-actual-token",
        "SUPABASE_URL": "https://your-supabase-url.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-actual-service-role-key"
      }
    }
  }
}

プレースホルダーの値を実際の認証情報に置き換えてください！

---

📖 設定オプション

サーバーでは、環境変数を指定する方法が 3 つサポートされています（優先順位順）：

1. MCP 設定の env セクション ⭐ 推奨 - すべてのユーザーに適しており、設定が自己完結しています
2. システム環境変数 - 認証情報を設定ファイルの外部に置きたい上級ユーザー向け
3. ラッパースクリプトを使用した .env ファイル - ローカル開発のみ（拡張性はありません）

各方法の詳細な設定手順については、こちらを参照してください： MCP_CONFIGURATION.md

よくある間違い： ❌ https://your-supabase-instance.example.com のようなプレースホルダー値をそのままにする
解決方法： ✅ すべてのプレースホルダーを、実際の URL と認証情報に置き換えてください！

---

Claude Desktop の場合

Claude Desktop の設定に追加します：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%/Claude/claude_desktop_config.json

NPX を使用する場合（推奨 - 常に最新版）

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "npx",
      "args": ["-y", "supabase-coolify-mcp-server"],
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-coolify-api-token",
        "SUPABASE_URL": "https://your-supabase-instance.example.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

グローバルインストールを使用する場合

まず、グローバルにインストールします：

npm install -g supabase-coolify-mcp-server

次に、設定します：

{
  "mcpServers": {
    "supabase-coolify": {
      "command": "supabase-coolify-mcp",
      "env": {
        "COOLIFY_API_URL": "http://localhost:8000",
        "COOLIFY_API_TOKEN": "your-coolify-api-token",
        "SUPABASE_URL": "https://your-supabase-instance.example.com",
        "SUPABASE_SERVICE_ROLE_KEY": "your-service-role-key"
      }
    }
  }
}

開発モード

# Using environment variables
export COOLIFY_API_URL="http://localhost:8000"
export COOLIFY_API_TOKEN="your-token"
export SUPABASE_URL="https://your-instance.example.com"
export SUPABASE_SERVICE_ROLE_KEY="your-key"

npm run dev

# Or with .env file
npm run dev

ビルド済みバージョンの実行

npm run build
npm start

🛠️ 利用可能なツール

データベースマイグレーションツール

list_migrations

すべてのデータベースマイグレーションとそのステータスを一覧表示します。

// No parameters required

deploy_migration

新しいデータベースマイグレーションをデプロイします。

{
  "sql": "CREATE TABLE users (id SERIAL PRIMARY KEY, email TEXT);",
  "name": "create_users_table"
}

execute_sql

Supabase データベースで生の SQL クエリを実行します。

{
  "sql": "SELECT * FROM users LIMIT 10;"
}

get_migration_status

指定したマイグレーションのステータスを取得します。

{
  "version": "20231201120000"
}

エッジ関数ツール

list_edge_functions

デプロイ済みのエッジ関数をすべて一覧表示します。

deploy_edge_function

新しいエッジ関数をデプロイします。

{
  "name": "hello-world",
  "code": "export default function handler(req) { return new Response('Hello World'); }",
  "verify_jwt": true
}

delete_edge_function

エッジ関数を削除します。

{
  "name": "hello-world"
}

get_edge_function_logs

エッジ関数のログを取得します。

{
  "name": "hello-world",
  "limit": 100
}

invoke_edge_function

エッジ関数を呼び出します。

{
  "name": "hello-world",
  "payload": { "key": "value" }
}

ストレージツール

list_storage_buckets

すべてのストレージバケットを一覧表示します。

create_storage_bucket

新しいストレージバケットを作成します。

{
  "id": "avatars",
  "public": true,
  "file_size_limit": 5242880
}

delete_storage_bucket

ストレージバケットを削除します。

{
  "id": "avatars"
}

認証・設定ツール

get_auth_config

認証設定を取得します。

update_auth_config

認証設定を更新します。

{
  "config": {
    "site_url": "https://myapp.com",
    "enable_signup": true
  }
}

check_supabase_health

すべての Supabase サービスの稼働状況を確認します。

get_supabase_version

Supabase のバージョン情報を取得します。

verify_setup ⭐

システムのセットアップを検証し、すべてのサービス（Coolify、Supabase、CLI）の健全性を確認します。

この包括的なツールでは、次の項目を確認します：

• Coolify の接続と認証
• Supabase の接続と認証
• データベースへのアクセス性
• CLI の利用可否
• 応答時間とサービスのステータス

戻り値： 検出された問題への推奨事項を含む、詳細なヘルスレポートです。

検証ガイドの詳細は、docs/VERIFICATION.md を参照してください。

Coolify 管理ツール

list_coolify_applications

すべての Coolify アプリケーションを一覧表示します。

get_coolify_application

特定のアプリケーションの詳細を取得します。

{
  "uuid": "app-uuid-here"
}

update_coolify_application_env

アプリケーションの環境変数を更新します。

{
  "uuid": "app-uuid-here",
  "env": {
    "NODE_ENV": "production",
    "API_KEY": "secret"
  }
}

deploy_coolify_application

Coolify アプリケーションをデプロイします。

{
  "uuid": "app-uuid-here"
}

start_coolify_application / stop_coolify_application / restart_coolify_application

アプリケーションのライフサイクルを管理します。

{
  "uuid": "app-uuid-here"
}

get_coolify_logs

アプリケーションのログを取得します。

{
  "uuid": "app-uuid-here",
  "lines": 100
}

デプロイツール

deploy_supabase_to_coolify

Coolify 上に Supabase インスタンスを丸ごとデプロイします。

{
  "name": "my-supabase",
  "config": {
    "postgres_version": "15",
    "enable_realtime": true,
    "enable_storage": true,
    "enable_auth": true,
    "custom_domain": "https://supabase.myapp.com",
    "environment_variables": {
      "CUSTOM_VAR": "value"
    }
  }
}

update_supabase_deployment

既存の Supabase デプロイを更新します。

{
  "uuid": "app-uuid-here",
  "config": {
    "enable_graphql": true
  }
}

get_deployment_status

Supabase デプロイのステータスを取得します。

{
  "uuid": "app-uuid-here"
}

📚 MCP リソース

サーバーは、MCP クライアントに次のリソースを公開します：

• supabase://migrations - すべてのデータベースマイグレーション
• supabase://edge-functions - すべてのエッジ関数
• supabase://storage-buckets - すべてのストレージバケット
• supabase://auth-config - 認証設定
• supabase://health - サービスの健全性ステータス
• coolify://applications - すべての Coolify アプリケーション
• coolify://services - すべての Coolify サービス
• coolify://databases - すべての Coolify データベース

🔒 セキュリティのベストプラクティス

1. API トークンをバージョン管理にコミットしないでください
2. 機密データには環境変数を使用してください
3. API トークンの権限は必要最小限に制限してください
4. トークンを定期的にローテーションしてください
5. サービスロールキーは安全なサーバー上でのみ使用してください
6. エッジ関数の JWT 検証を有効にしてください
7. すべての入力を検証してください（Zod スキーマによって自動的に行われます）
8. 本番環境へのデプロイ前にセットアップを検証してください
9. 設定ファイルに適切なファイル権限を設定してください：

chmod 600 ~/.env
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

🧪 テストと検証

ビルドと型チェック

# Run type checking
npm run typecheck

# Run linter
npm run lint

# Build project
npm run build

セットアップの検証

サーバーの起動後、すべてが正常に動作していることを確認します：

# Start the server
npm start

# Then ask Claude:
"Run verify_setup to check if everything is configured correctly"

検証ガイドの詳細は、docs/VERIFICATION.md を参照してください。

🔍 診断とテスト

問題を報告する前、または接続に問題がある場合は、組み込みの診断ツールを使用してください：

クイック診断

自動診断ツールを実行して、セットアップを確認します：

# Using npm
npm run diagnose

# Or on Windows
.\diagnose.ps1

# Or on Linux/Mac
./diagnose.sh

診断ツールは次の項目を自動的に確認します：

• ✅ .env ファイルの有無と設定
• ✅ 必須の環境変数
• ✅ Coolify API の接続と認証
• ✅ Supabase の接続と認証
• ✅ すべての Supabase サービスの健全性
• ✅ ネットワーク接続

期待される出力（正常時）

🟢 ALL CHECKS PASSED - MCP Server should work correctly

✅ Passed:   10
❌ Failed:   0
⚠️  Warnings: 0

よくある診断の問題

.env ファイルがない

❌ .env file NOT found!

対処方法：cp env.example .env を実行し、認証情報を入力して編集してください

プレースホルダー値

❌ ENV: COOLIFY_API_TOKEN: Contains placeholder value

対処方法：your-coolify-api-token-here を、Coolify Dashboard → Keys & Tokens で取得した実際のトークンに置き換えてください

Supabase キーが違う

❌ Supabase Authentication: Invalid service role key

対処方法：anon キーではなく、service_role キーを使用していることを確認してください！
次の場所から取得できます：Supabase Dashboard → Settings → API → service_role キー

接続に失敗した

❌ Coolify Connection: ECONNREFUSED

対処方法：Coolify が起動しており、設定された URL からアクセスできることを確認してください

認証情報の取得

Coolify API トークン：

1. Coolify Dashboard → Profile → Keys & Tokens → API Tokens
2. 「Create New Token」をクリックします
3. トークンをコピーします（一度しか表示されません！）
4. .env に COOLIFY_API_TOKEN として追加します

Supabase Service Role Key：

• Supabase Cloud：Dashboard → Settings → API → service_role キーをコピーします
• セルフホスト：Coolify のデプロイ環境変数で SERVICE_ROLE_KEY を確認します

クイックスタートガイド

詳細なトラブルシューティングについては、以下を参照してください：

• START_HERE.md - 診断機能付きクイックスタート
• DIAGNOSE_NOW.md - 手順に沿った診断
• TROUBLESHOOTING.md - 包括的なトラブルシューティングガイド

🐛 トラブルシューティング

よくある問題

1. 環境変数が不足している

エラー：Missing required environment variables: COOLIFY_API_URL, COOLIFY_API_TOKEN

解決方法：必要な環境変数がすべて設定されていることを確認します。.env ファイルまたは Claude Desktop の設定を確認してください。

2. 接続に失敗する

エラー：Failed to connect to Coolify API

解決方法：

• Coolify インスタンスが稼働していることを確認します
• API URL が正しいことを確認します（http:// または https:// を含めてください）
• API トークンに適切な権限があることを確認します
• ネットワーク接続を確認します

3. 認証に失敗する

エラー：Unauthorized または 401

解決方法：

• API トークンが正しいことを確認します
• トークンの有効期限が切れていないことを確認します
• トークンに必要な権限があることを確認します

4. MCP サーバーが表示されない

解決方法：

• Claude Desktop を再起動します
• お使いの OS に対応した設定ファイルのパスが正しいことを確認します
• 設定内の JSON 構文を確認します
• サーバーログにエラーがないか確認します

デバッグモード

デバッグ出力を有効にして実行します：

DEBUG=* npm start

📖 使用例

1. 新しい Supabase インスタンスをデプロイする

// Using the MCP tool
deploy_supabase_to_coolify({
  name: "production-supabase",
  config: {
    postgres_version: "15",
    enable_realtime: true,
    enable_storage: true,
    custom_domain: "https://api.myapp.com"
  }
})

2. データベースのマイグレーションをデプロイする

deploy_migration({
  name: "add_user_profiles",
  sql: `
    CREATE TABLE user_profiles (
      id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
      user_id UUID REFERENCES auth.users(id),
      display_name TEXT,
      avatar_url TEXT,
      created_at TIMESTAMP DEFAULT NOW()
    );
  `
})

3. Edge Function をデプロイする

deploy_edge_function({
  name: "send-email",
  code: `
    import { serve } from 'https://deno.land/[email protected]/http/server.ts'
    
    serve(async (req) => {
      const { to, subject, body } = await req.json()
      // Send email logic here
      return new Response(JSON.stringify({ success: true }))
    })
  `,
  verify_jwt: true
})

4. デプロイの健全性を監視する

// Check overall health
check_supabase_health()

// Get specific deployment status
get_deployment_status({ uuid: "your-app-uuid" })

// View logs
get_coolify_logs({ uuid: "your-app-uuid", lines: 100 })

🤝 貢献

貢献を歓迎します！お気軽に Pull Request を送信してください。

📄 ライセンス

MIT

🔗 リンク

• NPM パッケージ：https://www.npmjs.com/package/supabase-coolify-mcp-server
• GitHub リポジトリ：https://github.com/dj-pearson/supabase-coolify-mcp-server
• Coolify：https://coolify.io - セルフホスト可能な Heroku／Netlify の代替サービス
• Supabase：https://supabase.com - オープンソースの Firebase の代替サービス
• Model Context Protocol：https://modelcontextprotocol.io - MCP 仕様

📞 サポート

問題や質問については、以下をご利用ください：

• GitHub で issue を作成する
• トラブルシューティングのセクションを確認する
• Coolify と Supabase のドキュメントを参照する

---

注：この MCP サーバーは、Coolify 上のセルフホスト型 Supabase インスタンス向けに設計されています。環境変数と適切なトークン管理によってセキュリティを維持しながら、包括的な管理機能を提供します。