このドキュメントでは、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
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
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
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
AlloyDB の作成と接続に必要な Cloud APIs を有効にします。
[プロジェクトを確認] の手順で、[次へ] をクリックして、変更するプロジェクトの名前を確認します。
[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 が必要です。
- クラスタとそのプライマリ インスタンスを作成または選択します。
- 使用する環境のアプリケーションのデフォルト認証情報(ADC)を構成します。
- データベース ユーザーを作成または再利用します。ユーザー名とパスワードを入力できるよう準備します。
- スタンドアロンのコマンドライン ツール
- Gemini Code Assist を使用して IDE に統合
- Gemini CLI をインストールします。
- 次のコマンドを使用して、GitHub リポジトリから Gemini CLI 用の AlloyDB 拡張機能をインストールします。
gemini extensions install https://github.com/gemini-cli-extensions/alloydb
- 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"
- インタラクティブ モードで Gemini CLI を起動します。
CLI は、Gemini CLI 拡張機能用の AlloyDB 拡張機能とそのツールを自動的に読み込みます。これらのツールを使用して、データベースを操作できます。gemini
- Gemini CLI と
alloydb
拡張機能がインストールされ、構成されていることを確認します。 - Gemini CLI を使用するように Gemini Code Assist を構成する。
- Gemini Code Assist チャット内で自然言語を使用して AlloyDB インスタンスとのやり取りを開始します。
ツールボックスの最新バージョンをバイナリとしてダウンロードします。オペレーティング システム(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
バイナリを実行可能にします。
chmod +x toolbox
インストールを確認します。
./toolbox --version
- Claude Code をインストールします。
- プロジェクトのルートに
.mcp.json
ファイルが存在しない場合は作成します。 - 構成を追加し、環境変数を実際の値に置き換えて保存します。
- Claude Desktop を開き、[Settings] に移動します。
- [Developer] タブで [Edit Config] をクリックして、構成ファイルを開きます。
- 構成を追加し、環境変数を実際の値に置き換えて保存します。
- Claude Desktop を再起動します。
- 新しいチャット画面に、新しい MCP サーバーのハンマー(MCP)アイコンが表示されます。
- VS Code で Cline 拡張機能を開き、[MCP Servers] アイコンをタップします。
- [Configure MCP Servers] をクリックして構成ファイルを開きます。
- 次の構成を追加し、環境変数を実際の値に置き換えて保存します。
- プロジェクトのルートに
.cursor
ディレクトリが存在しない場合は作成します。 .cursor/mcp.json
ファイルが存在しない場合は作成したうえで、それを開きます。- 次の構成を追加し、環境変数を実際の値に置き換えて保存します。
- Cursor を開き、[Settings] > [Cursor Settings] > [MCP] に移動します。サーバーが接続されると、緑色のアクティブ ステータスが表示されます。
- VS Code を開き、プロジェクトのルートに
.vscode
ディレクトリが存在しない場合は作成します。 .vscode/mcp.json
ファイルが存在しない場合は作成したうえで、それを開きます。- 次の構成を追加し、環境変数を実際の値に置き換えて保存します。
- Windsurf を開き、Cascade アシスタントに移動します。
- MCP アイコンをクリックし、[Configure] をクリックして構成ファイルを開きます。
- 次の構成を追加し、環境変数を実際の値に置き換えて保存します。
AlloyDB 用の Gemini CLI 拡張機能を使用する
Gemini CLI は、コーディング、デバッグ、データ探索、コンテンツ作成を支援することで、開発ワークフローを支援するように設計されたオープンソースの AI エージェントです。このサービスの使命は、Data Cloud サービスや一般的なオープンソース データベースとやり取りするためのエージェント インターフェースを提供することです。
Gemini CLI との統合は、標準の MCP Toolbox 接続と比較して追加機能を提供する専用の拡張機能を通じて行われます。以降のセクションでは、インストール プロセスと一連のツールを提供する alloydb
拡張機能と alloydb-observability
拡張機能について説明します。オープンソースの拡張機能には、インストール、構成、使用例に関する詳細情報が含まれています。詳細については、Gemini CLI 拡張機能 - AlloyDB for PostgreSQL をご覧ください。
alloydb
拡張機能には、データベースのクエリ、AlloyDB リソースの管理、データベースの健全性のモニタリングを行うためのツールが含まれています。
カテゴリ | ツール | 自然言語プロンプトの例 |
---|---|---|
データベース オペレーション |
list_tables |
現在のデータベース内のすべてのテーブルを表示して。 |
execute_sql |
クエリ SELECT * FROM products WHERE category = 'electronics'; を実行します。 | |
list_active_queries |
データベースで実行されているクエリは何ですか? | |
get_query_plan |
「SELECT * FROM customers WHERE last_seen > '2025-08-01'」のクエリプランを説明して | |
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 |
reporting_user という名前の新しいデータベース ユーザーを作成します。 |
|
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 |
orders データベースに無効なインデックスがないか確認します。 |
alloydb-observability
拡張機能は、Gemini CLI から直接データベースのパフォーマンスと健全性を管理およびモニタリングするための統合インターフェースを提供します。
カテゴリ | ツール | 自然言語プロンプトの例 |
---|---|---|
オブザーバビリティ | get_system_metrics |
過去 1 時間の CPU 使用率などのシステム指標を教えてください。 |
get_query_metrics |
過去 15 分間のクエリ パフォーマンス指標を表示して。 |
AlloyDB 用の Gemini CLI 拡張機能は、次の 2 つの方法で使用できます。
Gemini CLI
Gemini Code Assist
Gemini CLI を使用するように Gemini Code Assist を構成することをおすすめします。この方法では、MCP サーバーを手動で構成する必要がなくなります。
MCP Toolbox for Databases を使用して他の IDE に接続する
このセクションでは、データベース向け MCP ツールボックスを使用して、さまざまなエージェントから AlloyDB インスタンスに接続する方法について説明します。ツールボックスは、IDE とデータベースの間に配置されるオープンソースの Model Context Protocol(MCP)サーバーとして機能し、AI ツールのコントロール プレーンを提供します。このセクションでは、パブリック IP アドレスまたはプライベート IP アドレスを使用して AlloyDB インスタンスに接続する手順について説明します。デフォルトでは、Toolbox はパブリック IP アドレスを使用しますが、構成例に示すように ALLOYDB_POSTGRES_IP_TYPE
環境変数を設定することで、プライベート IP 接続を構成できます。
MCP Toolbox for Databases をインストールする
IDE を AlloyDB に接続するには、AI エージェントをデータに接続するオープンソース サーバーである MCP Toolbox for Databases をインストールする必要があります。
クライアントを構成する
次のオプションからエージェント ツールを選択します。
Claude Code
{ "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" } } } }
Claude Desktop
{ "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" } } } }
Cline
{ "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" } } } }
サーバーが正常に接続されると、緑色のアクティブ ステータスが表示されます。
Cursor
{ "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" } } } }
Visual Studio Code(Copilot)
{ "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" } } } }
Windsurf
{ "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" } } } }