Claude Media
Claude CodeにAlloyDBプラグインを入れてAlloyDB for PostgreSQLに接続する
Claude CodeClaude連携チュートリアル

Claude CodeにAlloyDBプラグインを入れてAlloyDB for PostgreSQLに接続する

alloydbプラグインの導入から8つの接続設定、動作確認、権限の絞り方までを順に説明します。パスワードを設定画面に入れる前に確認したい点も扱います。

読了目安 約13分

Claude CodeからAlloyDB for PostgreSQLを操作するには、Google LLCが公開している alloydb プラグインを入れます。入れるコマンドは1行です。手間がかかるのは、そのあとの接続設定と権限の整理です。

このプラグインは、MCP Toolboxの alloydb-postgres プリビルドサーバーをClaude Codeのプラグインとして包んだものです。クラスターの作成からスキーマの確認、SQLの実行、性能調査まで、自然言語で指示できます。リポジトリのREADMEには、現在ベータ版(v1.0より前)で、初の安定版までに破壊的変更が入りうると書かれています。

動かすために先に揃えるもの

要件は5つです。1つでも欠けると、MCPサーバーの起動か接続の段階で止まります。

前提

導入前に揃える要件

  • Claude Code v2.1.94 以降

    READMEが示す下限です。claude --version で確かめます。

  • Node.js

    MCPサーバーは npx で起動します。npx がPATHになければ起動できません。

  • AlloyDB API を有効にした Google Cloud プロジェクト

    接続先のAlloyDBクラスターとインスタンスが、そのプロジェクトにある前提です。

  • Application Default Credentials

    実行する環境にADCが必要です。

  • IAM ロール

    AlloyDBクライアント(roles/alloydb.client)とAlloyDB管理者(roles/alloydb.admin)が挙がっています。

ADCの用意は、手元の端末なら次のコマンドが一例です。

claude --version
node --version
gcloud auth application-default login

インスタンスがプライベートIPの場合は、エージェントを同じVPCネットワーク内で動かす必要があります。エージェントの実行場所はネットワーク構成に合わせて選びます。接続経路は ALLOYDB_POSTGRES_IP_TYPE で PUBLIC、PRIVATE、PSC から選び、省略時は PUBLIC です。

接続設定の8項目を手元に用意する

接続情報は8つあります。必須は先頭の5つで、残りの3つは省略できます。

項目内容必須
ALLOYDB_POSTGRES_PROJECT内容GCPのプロジェクトID必須必須
ALLOYDB_POSTGRES_REGION内容インスタンスのリージョン必須必須
ALLOYDB_POSTGRES_CLUSTER内容クラスター ID必須必須
ALLOYDB_POSTGRES_INSTANCE内容インスタンスID必須必須
ALLOYDB_POSTGRES_DATABASE内容接続するデータベース名必須必須
ALLOYDB_POSTGRES_USER内容データベースのユーザー名必須任意
ALLOYDB_POSTGRES_PASSWORD内容そのユーザーのパスワード必須任意
ALLOYDB_POSTGRES_IP_TYPE内容IPの種類必須任意

READMEは、インストール前にこれらを端末の環境変数として設定する手順を示しています。値の例は次のとおりです。

export ALLOYDB_POSTGRES_PROJECT="my-gcp-project"
export ALLOYDB_POSTGRES_REGION="asia-northeast1"
export ALLOYDB_POSTGRES_CLUSTER="e-commerce-prod"
export ALLOYDB_POSTGRES_INSTANCE="e-commerce-prod-primary"
export ALLOYDB_POSTGRES_DATABASE="orders"

ユーザー名とパスワードは、ここでは設定しません。プラグインの設定画面にある説明では、省略したときの既定はIAMユーザーです。パスワードを持ち込まなくても接続できる構成を、まず試す順序です。

プラグインを入れて有効にする

導入はClaude Codeのセッション内で行います。手順は3段階です。

手順

導入から有効化まで

  1. 1

    環境変数を設定した端末で claude を起動する

    上の export を済ませた同じシェルで claude を実行します。

  2. 2

    プラグインを入れる

    /plugin install alloydb@claude-plugins-official を実行します。セッション内ではすぐには入らず、/plugin パネルがこのプラグインの詳細で開きます。内容を確認し、スコープを選んで進めます。

  3. 3

    有効になったかを確かめる

    /plugin list で一覧に出ているかを見ます。導入直後で反映されていなければ /reload-plugins を実行します。

シェルから入れる場合は、セッションを開かずに済みます。セットアップスクリプトに組み込むときの形です。

claude plugin install alloydb@claude-plugins-official

claude.comのマーケットプレイスにある alloydb のページでは、提供元はGoogle LLC、導入数は903と表示されていました。Claude Code向けの導入ボタンは、このシェル形式のコマンドをコピーします。

導入サマリーの最後の1文は、そのセッションですぐ使えるかを示します。Plugin is now active. に続けて「バンドルされたMCPサーバーに設定が必要」という趣旨の文が出たら、/plugin のInstalledタブでこのプラグインを選び、設定項目を開いて値を入れます。

設定が反映されないときの切り分け

READMEは端末の環境変数を案内していますが、Claude Code向けのマニフェスト(.claude-plugin/plugin.json)は別の書き方をしています。MCPサーバーの env が ${user_config.alloydb_postgres_project} のように、プラグインの設定項目(userConfig)の値を参照しているのです。

Claude Codeでは、userConfig はプラグインを有効にするときに入力を求める値です。つまり接続情報の入口は、少なくとも2つ考えられます。

  • 端末の環境変数(READMEの手順)
  • /plugin の設定画面(マニフェストの userConfig)

どちらの値が最終的にサーバーへ渡るかは、READMEにもマニフェストにも明記がありません。つながらないときは、片方だけに頼らず、設定画面に5つの必須項目が入っているかを見るのが早道です。

切り分け

つながらないときの確かめ順

  1. Q/mcp にこのプラグインのサーバーが出ていますか?
    答えが出ていない

    /plugin list で有効かを見ます。無効なら有効にして /reload-plugins を実行します。

    答えがはい
  2. Q`spawn npx ENOENT` が出ていませんか?
    答えが出ていない

    Node.jsがないか、npx がPATHにありません。Node.jsを入れます。

    答えがはい
  3. Q`could not find default credentials` が出ていませんか?
    答えが出ていない

    ADCが見つかっていません。gcloud auth application-default login を済ませ、Claude Codeを起動し直します。

    答えがはい

`Connection closed` が出る場合

データベースへの接続が張れていません。プロジェクト、リージョン、クラスター、インスタンス、データベースの5項目を、設定画面と環境変数の両方で見直します。プライベートIPのインスタンスなら、エージェントが同じVPC内にあるかも確かめます。

ここに挙げたエラー文言は、READMEのトラブルシューティング節にあるものです。READMEはGemini CLIの表示を例にしているため、Claude Codeの画面では文言の見た目が違うことがあります。

パスワードを設定画面に入れる前に

マニフェストを読むと、設定項目の alloydb_postgres_password は sensitive が false と定義されています。Claude Codeのリファレンスでは、sensitive を true にした値だけがマスク入力になり、安全な資格情報ストアに保存されます。false の値は settings.json の pluginConfigs に保存されます。

落とし穴

パスワードがマスクされず settings.json に残る定義になっている

この定義のまま設定画面にパスワードを入れると、入力はマスクされません。値は settings.json に書かれます。ユーザー名とパスワードは任意項目なので、まず空のままIAMユーザーでの接続を試してください。パスワード認証が必要な場合は、そのファイルをコミットや共有の対象にしないよう確認します。

ここで言えるのは、マニフェストの宣言とClaude Codeの保存先の対応までです。実際に書かれた settings.json の中身は、導入した環境で自分のファイルを開いて確かめるのが確実です。

動作確認は読み取りだけの質問から始める

つながったら、まず副作用のない質問で確かめます。READMEの使用例には、次のようなものがあります。

  • 「orders データベースのテーブルをすべて見せて」
  • 「products テーブルの列は何?」
  • 「過去30日の注文は何件?」
  • 「customers テーブルを表すPythonのデータクラスを生成して」

最初は接続先の確認に使えるものを選びます。たとえば「今の接続で SELECT current_user, current_database() を実行して、結果をそのまま見せて」と頼みます。IAMユーザーで入ったのか、狙ったデータベースに入ったのかが、1回の応答で分かります。

READMEの例には、クラスターを新規作成する依頼も並んでいます。同じプラグインで、課金が発生する操作まで頼めるということです。

管理系ツールを勝手に動かさせない

プラグインのツールは、7つのツールセットに分かれています。

ツールセットREADMEの説明の要点
adminREADMEの説明の要点クラスターとインスタンスの作成、作成状況の監視、構成情報の取得
access-managementREADMEの説明の要点ユーザー管理、権限とロールの確認、セキュリティ関連の設定値
dataREADMEの説明の要点スキーマの探索、ビューやトリガーの特定、任意のSQLの実行
monitorREADMEの説明の要点遅いクエリの調査、実行計画の分析、リソースを使うプロセスの特定、PromQLメトリクス
healthREADMEの説明の要点ストレージ最適化、インデックスの問題、テーブル統計、autovacuumの管理
optimizeREADMEの説明の要点PostgreSQL拡張の管理、メモリ割り当てなどの設定値
replicationREADMEの説明の要点レプリケーションの状態監視、同期状態の管理

data の「任意のSQLの実行」と、admin の「作成」が、事故につながりやすい部分です。Claude Code側では、このサーバーのツールを毎回確認つきにできます。プラグインが提供するサーバーのツール名は、mcp__plugin_<プラグイン名>_<サーバー名>__* の形で書きます。この場合はプラグイン名が alloydb、サーバー名が alloydb-postgres です。

{
  "permissions": {
    "ask": ["mcp__plugin_alloydb_alloydb-postgres__*"]
  }
}

これは、プラグイン提供サーバーの記法に当てはめた例です。個別のツール名を使った許可と拒否は、/permissions で実際のツール名を見てから足すと安全です。

もう1つの歯止めは、AlloyDB側の権限です。READMEは roles/alloydb.client と roles/alloydb.admin の両方を前提に挙げていますが、読み取りだけの用途で管理者ロールを外せるかどうかは、READMEに書かれていません。まずは検証用のプロジェクトで試すことを勧めます。本番のクラスターに、いきなり管理者ロールつきの認証情報を渡す運用は避けたいところです。

CLAUDE.mdに書く規約の例

接続先がつながったら、データベース操作のルールをプロジェクトの CLAUDE.md に置いておくと、依頼のたびに言わずに済みます。次は書き方の一例です。

## AlloyDB の操作ルール
- 接続先は orders データベースのみ。他のデータベースに切り替えない
- SELECT 以外の SQL は、実行前に文を提示して承認を待つ
- クラスターやインスタンスの作成・変更は、提案までにとどめる
- 重いクエリは先に EXPLAIN で実行計画を見せてから実行する

規約はClaudeへの依頼文であり、強制力はありません。強制したい部分は、前の節の permissions とAlloyDB側のロールで受け持ちます。

ツールではなくスキルとして使う選択肢

READMEには、MCPのツールを読み込めないエージェント向けに、同じツールセットをスキルとして生成する方法も載っています。リポジトリの generate_skills.sh を使う方法と、--prebuilt alloydb-postgres skills-generate を直接実行する方法です。以前のプラグインにはツール由来のスキルが同梱されていたと、READMEに書かれています。Claude Codeで通常の導入ができているなら、この生成を使う場面はありません。

導入後の管理

プラグインの導入後に気にしたいのは、コンテキストの消費と棚卸しです。常時読み込まれるツール定義の重さは、claude plugin detailsでプラグインのコンテキスト消費を測るで測れます。導入済みの一覧を機械可読で取る方法はclaude plugin list --jsonで導入済みプラグインを棚卸しするにあります。

組織の管理設定でプラグイン以外のMCP追加が止められている環境では、claude mcp addが失敗する原因が参考になります。Google Cloud側の別サービスとの比較には、Claude BigQuery連携の手順が参考になります。

まとめ

導入は /plugin install alloydb@claude-plugins-official の1行で終わります。時間を使うのは、8つの接続情報、ADC、IAMロールの準備です。

動作確認は current_user を返す読み取りから入り、管理系のツールには permissions.ask で歯止めをかけます。パスワードは設定画面に入れる前に、保存先が settings.json になる定義であることを思い出してください。まずIAMユーザーでの接続を試し、ベータ版であることを前提に、検証用のクラスターから使い始めるのが無理のない順序です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →