Claude CodeにCloud SQL for PostgreSQLプラグインを入れて接続・操作する

Claude CodeからCloud SQL for PostgreSQLを操作するには、Google LLCが公開している cloud-sql-postgresql プラグインを入れます。入れるコマンドは1行です。つまずきやすいのは、その前後にある接続設定とIAMユーザーの追加です。

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

同じ作りでAlloyDB向けの兄弟プラグインもあります。AlloyDBが対象ならClaude CodeにAlloyDBプラグインを入れてAlloyDB for PostgreSQLに接続するを読んでください。この記事はCloud SQLに絞ります。

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

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

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

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

IAMユーザーをインスタンスに足しておく

READMEの注意書きに、見落としやすい前提があります。CLOUD_SQL_POSTGRES_USER と CLOUD_SQL_POSTGRES_PASSWORD を設定しない場合、サーバーは手元で有効なIAMユーザーの認証情報を使います。その場合は、そのIAMユーザーをCloud SQLインスタンスのデータベースユーザーとして追加しておく必要があります。

IAMロールを付けただけでは、データベースにログインできません。パスワードを使わない構成を選ぶなら、先にこの追加を済ませます。追加の手順はGoogle Cloudの「Creating a database user」の説明にあたります。

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

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

IPの種類を省略すると PUBLIC になります。インスタンスがプライベートIPなら、エージェントを同じVPCネットワーク内で動かす必要があります。

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

export CLOUD_SQL_POSTGRES_PROJECT="my-gcp-project"
export CLOUD_SQL_POSTGRES_REGION="asia-northeast1"
export CLOUD_SQL_POSTGRES_INSTANCE="e-commerce-prod"
export CLOUD_SQL_POSTGRES_DATABASE="orders"

AlloyDB版にある「クラスターID」の項目は、Cloud SQL版にはありません。インスタンス単位で指定します。

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

導入はClaude Codeのセッション内で行います。

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

claude plugin install cloud-sql-postgresql@claude-plugins-official

claude.comのマーケットプレイスにある cloud-sql-postgresql のページでは、提供元はGoogle LLC、導入数は2,520と表示されていました。マニフェスト(.claude-plugin/plugin.json)のバージョンは0.4.0です。このバージョンの変更履歴には、接続に成功した直後に SELECT 1 を実行する変更が入っています。接続できていない状態は、サーバーの起動直後に表に出やすくなっています。

設定の入口は環境変数と設定画面の2つある

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

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

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

どちらの値が最終的にサーバーへ渡るかは、READMEにもマニフェストにも書かれていません。つながらないときは、設定画面に必須の4項目(プロジェクト、リージョン、インスタンス、データベース)が入っているかを先に見ます。

つながらないときの切り分け

READMEのトラブルシューティング節に、よくあるエラーが4つ載っています。上から順に確かめると、原因を絞れます。

READMEの例はGemini CLIの表示です。Claude Codeの画面では、文言の見た目が違うことがあります。

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

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

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

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

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

• 「orders データベースのテーブルをすべて見せて」
• 「products テーブルの列は何?」
• 「過去30日の注文は何件で、よく買われた上位5品目は?」
• 「customers テーブルを表すPythonのデータクラスを生成して」

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

READMEの例には、インスタンスやユーザーを新規作成する依頼も並んでいます。同じプラグインで、課金や権限の変更が起きる操作まで頼めるということです。

8つのツールセットと、動かさせたくない部分

プラグインのツールは、MCP Toolboxのプリビルドサーバーが提供します。READMEは8つのツールセットに分けて説明しています。

AlloyDB版の表と見比べると、access-management と optimize に当たる区分がなく、代わりにLifecycleとVector Assistがあります。ツールの全一覧は、READMEが案内するMCP Toolboxのプリビルド設定を見ます。

事故につながりやすいのは、Dataの「任意のSQLの実行」と、AdminやLifecycleの「作成」「復元」です。Claude Code側では、このサーバーのツールを毎回確認つきにできます。プラグインが提供するサーバーのツール名は mcp__plugin_<プラグイン名>_<サーバー名>__* の形です。ここではプラグイン名が cloud-sql-postgresql、サーバー名が cloud-sql-postgres で、ハイフンはそのまま残ります。

{
  "permissions": {
    "ask": ["mcp__plugin_cloud-sql-postgresql_cloud-sql-postgres__*"]
  }
}

これは、プラグイン提供サーバーの記法に当てはめた例です。個別のツール名で許可と拒否を足すときは、/permissions で実際の名前を見てからにします。プラグインを入れたときの同梱MCPの仕組みは、プラグイン同梱のMCPサーバーで詳しく扱っています。

もう1つの歯止めは、Google Cloud側の権限です。READMEは roles/cloudsql.client と roles/cloudsql.admin の両方を前提に挙げていますが、読み取りだけの用途で管理者ロールを外せるかどうかは、READMEに書かれていません。まずは検証用のプロジェクトで試します。

公式リポジトリのevalsは何を試しているか

リポジトリには evals ディレクトリがあり、Claude Code用のデータセット(claude_dataset.json)が入っています。シナリオは4つで、いずれも最大3ターンです。

実行設定のモデル定義は、Claude Code 2.1.119と claude-opus-4-7 をVertex AI経由で動かす指定です。採点は目標達成度、振る舞い、ターン数などの指標で、判定側にはGeminiのモデルが指定されています。

この表から、プラグインが日常の調査として想定している依頼がつかめます。インスタンスの状態、スキーマ、遅いクエリ、CPUの順に、読み取りだけで状況を絞り込む流れです。データセットの期待値は、スキル名とスクリプト名(.js)で書かれています。READMEによればツールは以前スキルとして配布されていたので、評価データがこの時期の形を引き継いでいる可能性があります。MCPツール経由の導入でも同じ結果になるかは、このデータセットからは言えません。自分の環境では、同じ依頼を投げて呼び出されるツールを見て確かめます。

CLAUDE.mdに書く規約の例

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

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

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

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

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

導入後の管理

導入後は、ほかのプラグインとの位置関係と、マニフェストの書式を押さえておくと設定の見直しが楽になります。公式マーケットプレイスに並ぶほかのプラグインとの違いは、Claude Code公式マーケットプレイスのプラグイン一覧にまとめています。マニフェストの userConfig や sensitive の書式は、plugin.jsonのスキーマ解説で確認できます。

まとめ

導入は /plugin install cloud-sql-postgresql@claude-plugins-official の1行で終わります。時間を使うのは、7つの接続情報、ADC、IAMロール、そしてIAMユーザーのインスタンスへの追加です。

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