AlloyDB for PostgreSQL を MCP、Gemini CLI、その他のエージェントで使用する

このドキュメントでは、Model Context Protocol（MCP）をサポートするさまざまなエージェントに AlloyDB インスタンスを接続する方法について説明します。

Gemini CLI 用の専用の AlloyDB 拡張機能を使用することをおすすめします。Gemini CLI は、基盤となる MCP サーバーを拡張機能に直接統合するため、個別のサーバー設定を行う必要がありません。Gemini CLI を使用するように Gemini Code Assist を構成できます。これにより、IDE 内でも同様の設定上のメリットを得られます。

また、MCP をサポートする他の IDE やエージェントは、データベース向け MCP ツールボックスを介して接続できます。このツールボックスは、AI エージェントをデータに接続するように設計されたオープンソースの MCP サーバーです。認証や接続プーリングなどのタスクを処理し、IDE から自然言語でデータを直接操作できます。

始める前に

AlloyDB インスタンスに接続して使用可能なツールを使用するには、次のいずれかの Identity and Access Management（IAM）ロール、または同等の権限を持つカスタムロールが必要です。

タスク	ロール名	必要な Identity and Access Management（IAM）ロール
読み取り専用ツールを使用して AlloyDB リソースを一覧表示して取得する	AlloyDB 閲覧者	roles/alloydb.viewer
インスタンスに接続してクエリを実行する	Cloud AlloyDB クライアント	roles/alloydb.client
	Service Usage ユーザー	roles/serviceusage.serviceUsageConsumer
管理タスク（クラスタ、インスタンス、ユーザーの作成や管理など）を行う	AlloyDB 管理者	roles/alloydb.admin
オブザーバビリティ拡張機能を使用する	モニタリング閲覧者	roles/monitoring.viewer

AlloyDB インスタンスに接続する前に、次の手順でプロジェクトとデータベースを設定します。

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. AlloyDB の作成と接続に必要な Cloud APIs を有効にします。

   API を有効にする

   1. [プロジェクトを確認] の手順で、[次へ] をクリックして、変更するプロジェクトの名前を確認します。

   2. [API を有効にする] の手順で、[有効にする] をクリックして、次の機能を有効にします。

      • AlloyDB API
      • Compute Engine API
      • Cloud Resource Manager API
      • Service Networking API

      AlloyDB と同じ Google Cloud プロジェクトにある VPC ネットワークを使用して AlloyDB へのネットワーク接続を構成する場合は、Service Networking API が必要です。

      別の Google Cloud プロジェクトに存在する VPC ネットワークを使用して AlloyDB へのネットワーク接続を構成する場合は、Compute Engine API と Cloud Resource Manager API が必要です。

2. クラスタとそのプライマリ インスタンスを作成または選択します。
3. 使用する環境のアプリケーションのデフォルト認証情報（ADC）を構成します。
4. データベース ユーザーを作成または再利用します。ユーザー名とパスワードを入力できるよう準備します。

AlloyDB 用 Gemini CLI 拡張機能を使用する

注: AlloyDB Gemini CLI 拡張機能は、データベース向け MCP ツールボックスを基盤としています。データベース向け MCP ツールボックスは現在ベータ版（v1.0 より前）であり、最初の安定版リリース（v1.0）まで互換性を破る変更が行われる可能性があります。

Gemini CLI は、開発ワークフローを効率化できるオープンソースの AI エージェントであり、コーディング、デバッグ、データ探索、コンテンツ作成を支援します。データクラウド サービスや一般的なオープンソース データベースを操作できるエージェント インターフェースを提供することを目的としています。

Gemini CLI との統合は、標準の MCP ツールボックス接続と比べて追加機能を提供する専用の拡張機能を通じて行われます。以降のセクションでは、インストール プロセスと一連のツールを提供する、alloydb 拡張機能と alloydb-observability 拡張機能について説明します。オープンソースの拡張機能には、インストール、構成、使用例に関する詳細情報が含まれています。詳細については、Gemini CLI 拡張機能 - AlloyDB for PostgreSQL をご覧ください。

alloydb 拡張機能には、データベースのクエリ、AlloyDB リソースの管理、データベースの健全性のモニタリングを行うためのツールが含まれています。

以下の例では、次のテーブルを含むサンプル ecommerce データベースを使用します。

• products: product_id、product_name、category、price などの商品情報を含みます。
• customers: customer_id、first_name、last_name、email などの顧客データを保存します。
• orders: order_id、customer_id、order_date などの注文情報を含みます。

カテゴリ	ツール	自然言語プロンプトの例
データベース オペレーション	list_tables	現在のデータベース内のすべてのテーブルを表示して。
	execute_sql	「ノートパソコン」のカテゴリで最も高額な商品を 10 個表示して。
	list_active_queries	データベースで実行されているクエリは何？
	get_query_plan	過去 6 か月間に注文のなかった顧客をすべて検索するクエリのクエリプランについて説明して。
	list_available_extensions	インストールできる拡張機能は何？
	list_installed_extensions	インストールされているすべての拡張機能を一覧で表示して。
リソース管理 クラスタ、インスタンス、ユーザー	create_cluster	us-east1 リージョンに sales-quarterly-db という名前の AlloyDB クラスタを作成して。
	get_cluster	クラスタ sales-quarterly-db の詳細情報を収集して。
	list_clusters	すべての AlloyDB クラスタを一覧で表示して。
	create_instance	sales-quarterly-db クラスタに新しい読み取りインスタンスを作成して。
	get_instance	インスタンス sales-quarterly-db-rp の情報を表示して。
	list_instances	sales-quarterly-db クラスタ内のすべてのインスタンスを一覧で表示して。
	create_user	注: create_user ツールでは、次の 2 種類のデータベース ユーザーを作成できます。 組み込み認証を使用するデータベース ユーザー: これらのユーザーはデータベース内で管理され、パスワードで認証されます。 IAM ユーザー: これらのユーザーは IAM で管理され、IAM 認証情報を使用して認証されます。 組み込み認証を使用してデータベース ユーザーを作成する場合は、パスワードを指定する必要があります。IAM ユーザーを作成するときは、IAM プリンシパルを指定する必要があります。 パスワード report_password を使用して、reporting_user という名前の新しいデータベース ユーザーを作成して。 [e-mail] の新しい IAM データベース ユーザーを作成して。
	get_user	ユーザー reporting_user の情報を収集して。
	list_users	すべてのデータベース ユーザーを一覧で表示して。
	wait_for_operation	オペレーション operation-163562789 のステータスは？
データベースの健全性とメンテナンス	list_autovacuum_configurations	現在の autovacuum 構成を表示して。
	list_memory_configurations	プライマリ インスタンスの現在のメモリ構成は？
	list_top_bloated_tables	最も肥大化したテーブルの上位 5 つを一覧で表示して。
	list_replication_slots	アクティブなレプリケーション スロットをすべて表示して。
	list_invalid_indexes	ecommerce データベースに無効なインデックスがないか確認して。

alloydb-observability 拡張機能は、Gemini CLI から直接データベースのパフォーマンスと健全性を管理およびモニタリングするための統合インターフェースを提供します。

カテゴリ	ツール	自然言語プロンプトの例
オブザーバビリティ	get_system_metrics	過去 1 時間の CPU 使用率などのシステム指標は何？
	get_query_metrics	過去 15 分間のクエリ パフォーマンス指標を表示して。

AlloyDB 用 Gemini CLI 拡張機能は、次の 2 つの方法で使用できます。

• スタンドアロンのコマンドライン ツール
• Gemini Code Assist を使用して IDE に統合する

Gemini CLI

1. Gemini CLI をインストールします。
2. 次のコマンドを使用して、GitHub リポジトリから Gemini CLI 用の AlloyDB 拡張機能をインストールします。

   gemini extensions install https://github.com/gemini-cli-extensions/alloydb
   

3. AlloyDB インスタンスに接続するための環境変数を設定します。

   export ALLOYDB_POSTGRES_PROJECT="PROJECT_ID"
   export ALLOYDB_POSTGRES_REGION="REGION"
   export ALLOYDB_POSTGRES_CLUSTER="CLUSTER_NAME"
   export ALLOYDB_POSTGRES_INSTANCE="INSTANCE_NAME"
   export ALLOYDB_POSTGRES_DATABASE="DATABASE_NAME"
   

   AlloyDB 用の Gemini CLI 拡張機能は、デフォルトで認証に [アプリケーションのデフォルト認証情報（ADC）]（/authentication/application-default-credentials）を使用します。データベース ユーザーとして接続する場合は、次の省略可能な環境変数を設定します。

   #Optional: Set for database user authentication
   export ALLOYDB_POSTGRES_USER="USERNAME"
   export ALLOYDB_POSTGRES_PASSWORD="PASSWORD"
   

   プライベート IP アドレスを使用して接続するには、次の環境変数も設定する必要があります。

   export ALLOYDB_POSTGRES_IP_TYPE="private"
   

4. インタラクティブ モードで Gemini CLI を起動します。

   gemini
   

   CLI は、Gemini CLI 拡張機能用の AlloyDB 拡張機能とそのツールを自動的に読み込みます。これらのツールを使用して、データベースを操作できます。

Gemini Code Assist

Gemini CLI を使用するように Gemini Code Assist を構成することをおすすめします。この方法では、MCP サーバーを手動で構成する必要がなくなります。

1. Gemini CLI と alloydb 拡張機能がインストールされ、構成されていることを確認します。
2. Gemini CLI を使用するように Gemini Code Assist を構成します。
3. Gemini Code Assist チャット内で自然言語を使用して AlloyDB インスタンスとのやり取りを開始します。

データベース向け MCP ツールボックスを使用して他の IDE に接続する

このセクションでは、データベース向け MCP ツールボックスを使用して、さまざまなエージェントから AlloyDB インスタンスに接続する方法について説明します。このツールボックスは、IDE とデータベースの間に配置されるオープンソースの Model Context Protocol（MCP）サーバーとして機能し、AI ツール用のコントロール プレーンを提供します。このセクションでは、パブリック IP アドレスまたはプライベート IP アドレスを使用して AlloyDB インスタンスに接続する手順について説明します。デフォルトでは、このツールボックスはパブリック IP アドレスを使用しますが、構成例に示すように ALLOYDB_POSTGRES_IP_TYPE 環境変数を設定することで、プライベート IP 接続を構成できます。

データベース向け MCP ツールボックスをインストールする

IDE を AlloyDB に接続するには、データベース向け MCP ツールボックスをインストールする必要があります。これは、AI エージェントをデータに接続するオープンソース サーバーです。

1. ツールボックスの最新バージョンをバイナリとしてダウンロードします。オペレーティング システム（OS）と CPU アーキテクチャに対応するバイナリを選択します。ツールボックス バージョン v0.15.0 以降を使用する必要があります。

   linux/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox
   
   

   darwin/arm64

   curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox
   
   

   darwin/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox
   
   

   windows/amd64

   curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox
   
   

2. バイナリを実行可能にします。

   chmod +x toolbox
   

3. インストールを確認します。

   ./toolbox --version
   

クライアントを構成する

次のオプションからエージェント ツールを選択します。

Claude Code

1. Claude Code をインストールします。
2. プロジェクトのルートに .mcp.json ファイルが存在しない場合は作成します。
3. 構成を追加し、環境変数を実際の値に置き換えて保存します。




{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

注: プライベート IP アドレスを使用して接続するには、env オブジェクトに "ALLOYDB_POSTGRES_IP_TYPE": "private" という行を追加します。

Claude Desktop

1. Claude Desktop を開き、[Settings] に移動します。
2. [Developer] タブで [Edit Config] をクリックして、構成ファイルを開きます。
3. 構成を追加し、環境変数を実際の値に置き換えて保存します。




{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

注: プライベート IP アドレスを使用して接続するには、env オブジェクトに "ALLOYDB_POSTGRES_IP_TYPE": "private" という行を追加します。

4. Claude Desktop を再起動します。
5. 新しいチャット画面に、新しい MCP サーバーのハンマー（MCP）アイコンが表示されます。

Cline

1. VS Code で Cline 拡張機能を開き、[MCP Servers] アイコンをタップします。
2. [Configure MCP Servers] をクリックして構成ファイルを開きます。
3. 次の構成を追加し、環境変数を実際の値に置き換えて保存します。




{
  "mcpServers": {
    "alloydb": {
     "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}


サーバーが正常に接続されると、緑色のアクティブ ステータスが表示されます。



注: プライベート IP アドレスを使用して接続するには、env オブジェクトに "ALLOYDB_POSTGRES_IP_TYPE": "private" という行を追加します。

Cursor

1. プロジェクトのルートに .cursor ディレクトリが存在しない場合は作成します。
2. .cursor/mcp.json ファイルが存在しない場合は作成したうえで、それを開きます。
3. 次の構成を追加し、環境変数を実際の値に置き換えて保存します。

{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

注: プライベート IP アドレスを使用して接続するには、env オブジェクトに "ALLOYDB_POSTGRES_IP_TYPE": "private" という行を追加します。

4. Cursor を開き、[Settings] > [Cursor Settings] > [MCP] に移動します。サーバーが接続されると、緑色のアクティブ ステータスが表示されます。

Visual Studio Code（Copilot）

1. VS Code を開き、プロジェクトのルートに .vscode ディレクトリが存在しない場合は作成します。
2. .vscode/mcp.json ファイルが存在しない場合は作成したうえで、それを開きます。
3. 次の構成を追加し、環境変数を実際の値に置き換えて保存します。

{
  "servers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
        "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
        "ALLOYDB_POSTGRES_REGION": "REGION",
        "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
        "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
        "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
        "ALLOYDB_POSTGRES_USER": "USERNAME",
        "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

注: プライベート IP アドレスを使用して接続するには、env オブジェクトに "ALLOYDB_POSTGRES_IP_TYPE": "private" という行を追加します。

Windsurf

1. Windsurf を開き、Cascade アシスタントに移動します。
2. MCP アイコンをクリックし、[Configure] をクリックして構成ファイルを開きます。
3. 次の構成を追加し、環境変数を実際の値に置き換えて保存します。

{
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

注: プライベート IP アドレスを使用して接続するには、env オブジェクトに "ALLOYDB_POSTGRES_IP_TYPE": "private" という行を追加します。