Supabase MCP サーバー実装計画

このドキュメントでは、Supabase に接続し、GitHub Copilot などの AI アシスタントが Supabase データベースと対話できるようにする Model Context Protocol (MCP) サーバーを作成する計画の概要を説明します。

概要

Supabase MCPサーバーは、AIアシスタント（GitHub Copilotなど）とSupabaseデータベース間のブリッジとして機能します。これにより、AIは以下のことが可能になります。

データベーススキーマを理解する
テーブルと関係について知る
クエリ作成の支援
データモデルに関連するコンテキストに応じた提案を提供する

前提条件

Node.js 18以上がインストールされている
npm または yarn パッケージマネージャー
管理者APIキーを使用したSupabaseプロジェクト
Copilot/MCP サポート付き VS Code
ギット

実装手順

1. サーバーパッケージを作成する

mkdir mcp-server-supabase
cd mcp-server-supabase
npm init -y

2. 依存関係をインストールする

npm install @supabase/supabase-js @modelcontextprotocol/server dotenv

3. 基本的なサーバー構造

次のファイルを作成します。

src/index.js - メインエントリポイント
src/supabase-client.js - Supabase 接続処理
src/schema-provider.js - データベーススキーマの抽出
src/query-handler.js - 安全なクエリ実行
.env.example - 環境変数テンプレート
config.js - 構成管理

4. サーバー実装の詳細

src/index.js

このファイルは MCP サーバーを初期化し、コンポーネントを接続します。

const { MCPServer } = require('@modelcontextprotocol/server');
const { getSupabaseClient } = require('./supabase-client');
const { SchemaProvider } = require('./schema-provider');
const { QueryHandler } = require('./query-handler');
const config = require('./config');

async function main() {
  try {
    // Initialize Supabase client
    const supabaseClient = getSupabaseClient(config.supabase.url, config.supabase.key);
    
    // Create providers
    const schemaProvider = new SchemaProvider(supabaseClient);
    const queryHandler = new QueryHandler(supabaseClient, config.security.allowedQueries);
    
    // Initialize MCP server
    const server = new MCPServer({
      name: 'mcp-server-supabase',
      version: '1.0.0',
    });
    
    // Register handlers
    server.registerHandler('getSchema', async () => {
      return await schemaProvider.getFullSchema();
    });
    
    server.registerHandler('getTableInfo', async (params) => {
      return await schemaProvider.getTableInfo(params.tableName);
    });
    
    server.registerHandler('executeQuery', async (params) => {
      return await queryHandler.execute(params.query, params.params);
    });
    
    // Start the server
    await server.start();
    console.log('MCP Supabase server is running');
  } catch (error) {
    console.error('Failed to start MCP server:', error);
    process.exit(1);
  }
}

main();

src/supabase-client.js

const { createClient } = require('@supabase/supabase-js');

function getSupabaseClient(url, apiKey) {
  if (!url || !apiKey) {
    throw new Error('Supabase URL and API key must be provided');
  }
  
  return createClient(url, apiKey, {
    auth: { persistSession: false },
  });
}

module.exports = { getSupabaseClient };

src/スキーマプロバイダー.js

class SchemaProvider {
  constructor(supabaseClient) {
    this.supabase = supabaseClient;
  }
  
  async getFullSchema() {
    // Query Supabase for full database schema
    const { data, error } = await this.supabase
      .rpc('get_schema_information', {});
    
    if (error) throw new Error(`Failed to get schema: ${error.message}`);
    
    return data;
  }
  
  async getTableInfo(tableName) {
    // Get detailed information about a specific table
    const { data, error } = await this.supabase
      .rpc('get_table_information', { table_name: tableName });
    
    if (error) throw new Error(`Failed to get table info: ${error.message}`);
    
    return data;
  }
}

module.exports = { SchemaProvider };

src/クエリハンドラ.js

class QueryHandler {
  constructor(supabaseClient, allowedQueryTypes = ['SELECT']) {
    this.supabase = supabaseClient;
    this.allowedQueryTypes = allowedQueryTypes; 
  }
  
  validateQuery(queryString) {
    // Basic SQL injection prevention and query type validation
    const normalizedQuery = queryString.trim().toUpperCase();
    
    // Check if the query starts with allowed query types
    const isAllowed = this.allowedQueryTypes.some(
      type => normalizedQuery.startsWith(type)
    );
    
    if (!isAllowed) {
      throw new Error(`Query type not allowed. Allowed types: ${this.allowedQueryTypes.join(', ')}`);
    }
    
    return true;
  }
  
  async execute(queryString, params = {}) {
    // Validate query before execution
    this.validateQuery(queryString);
    
    // Execute the query through Supabase
    const { data, error } = await this.supabase
      .rpc('execute_query', { query_string: queryString, query_params: params });
    
    if (error) throw new Error(`Query execution failed: ${error.message}`);
    
    return data;
  }
}

module.exports = { QueryHandler };

config.js

require('dotenv').config();

module.exports = {
  supabase: {
    url: process.env.SUPABASE_URL,
    key: process.env.SUPABASE_SERVICE_KEY,
  },
  server: {
    port: process.env.PORT || 3000,
  },
  security: {
    allowedQueries: process.env.ALLOWED_QUERY_TYPES 
      ? process.env.ALLOWED_QUERY_TYPES.split(',') 
      : ['SELECT'],
  }
};

.env.example

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_SERVICE_KEY=your-service-key
PORT=3000
ALLOWED_QUERY_TYPES=SELECT

5. Supabaseデータベース関数

Supabase で次のストアドプロシージャを作成する必要があります。

get_schema_information() - データベーススキーマを返す
get_table_information(table_name TEXT) - 特定のテーブルに関する情報を返します
execute_query(query_string TEXT, query_params JSONB) - クエリを安全に実行します

サーバーアーキテクチャ

┌─────────────────────┐      ┌───────────────────┐
│                     │      │                   │
│  VS Code + Copilot  │◄────►│   MCP Protocol    │
│                     │      │                   │
└─────────────────────┘      └─────────┬─────────┘
                                      │
                                      ▼
                            ┌─────────────────────┐
                            │                     │
                            │ Supabase MCP Server │
                            │                     │
                            └─────────┬───────────┘
                                      │
                                      ▼
                            ┌─────────────────────┐
                            │                     │
                            │  Supabase Database  │
                            │                     │
                            └─────────────────────┘

構成

Supabase MCP サーバーを VS Code のsettings.jsonに追加します。

"mcp": {
  "inputs": [],
  "servers": {
    // ...existing servers...
    "mcp-server-supabase": {
      "command": "node",
      "args": [
        "/path/to/mcp-server-supabase/src/index.js"
      ],
      "env": {
        "SUPABASE_URL": "https://your-project-ref.supabase.co",
        "SUPABASE_SERVICE_KEY": "your-service-key",
        "ALLOWED_QUERY_TYPES": "SELECT"
      }
    }
  }
}

セキュリティに関する考慮事項

APIキー管理:
- 必要最小限の権限を持つスコープ付き API キーを使用する
- APIキーを安全に保存し、バージョン管理にコミットしないでください
- キーローテーション戦略の使用を検討する
クエリの制限:
- 安全のため、SELECTのみをデフォルトとする
- クエリ許可リストアプローチの実装を検討する
- 不正使用を防ぐためにレート制限を追加する
データ保護:
- 個人情報や機密データの公開を避ける
- Supabaseで行レベルのセキュリティを実装する
- 機密性の高いフィールドにデータマスキングを追加することを検討してください

インストールガイド

地域開発

リポジトリをクローンする
git clone https://github.com/yourusername/mcp-server-supabase.git cd mcp-server-supabase
依存関係をインストールする
npm install
例から.envファイルを作成する
cp .env.example .env
Supabaseの認証情報で.envを編集します
サーバーを起動する
node src/index.js

VSコード統合

VS Codeのsettings.jsonサーバー構成で更新します
VS Codeを再起動する
VS Code MCPパネルでサーバーが実行中であることを確認します

使用例

統合すると、Supabase MCP サーバーをさまざまな方法で使用できるようになります。

スキーマ探索:
What tables do I have in my Supabase database?
テーブル情報:
What columns are in the users table?
クエリのサポート:
Help me write a query to get all users who signed up in the last 7 days

トラブルシューティング

サーバーが起動しません

Node.jsのバージョンを確認してください（18歳以上である必要があります）
Supabaseの資格情報を確認する
ターミナルでエラーログを確認する

スキーマが読み込まれません

Supabaseサービスキーに必要な権限があることを確認してください
データベース関数が適切に作成されていることを確認する

VS Codeに接続できません

settings.json のサーバーパスが正しいことを確認してください
構成変更後にVS Codeを再起動します
サーバープロセスが実行中であることを確認する

Supabase MCP Server

Integrations