Claude CodeにBigQueryプラグインを入れて接続・分析する

Claude CodeでBigQueryのデータを自然言語で扱うなら、Google LLCが公開している bigquery-data-analytics プラグインを入れます。導入コマンドは1行です。入れたあとに決めることは、課金の歯止め、書き込みの禁止、予測をどの経路で走らせるかの3つです。

このプラグインは、MCP Toolboxの bigquery プリビルドサーバーをClaude Code用に包み、AI関数のためのスキルを1つ同梱したものです。リポジトリのREADMEには、現在ベータ版(v1.0より前)で、初の安定版までに破壊的変更が入る可能性があると書かれています。claude.comのマーケットプレイスには、導入数も表示されています。

MCPサーバーを自分で登録して接続する手順は、Claude BigQuery連携の手順とBigQueryをClaudeで自然言語のまま分析する方法にあります。ここでは、プラグインで入れた場合に何が付いてくるかを扱います。

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

要件はREADMEの前提節にあります。Claude Codeのバージョンから順に確かめます。

手元の端末なら、ADCの用意は次のコマンドで済みます。

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

AI関数(後述のスキル)まで使う場合の追加条件は3つです。Vertex AI APIを有効にすること、roles/bigquery.connectionUser と roles/aiplatform.user を付けること、そしてBigQuery側にCloud Resource Connectionを作っておくことです。最後の1つはREADMEではなく、同梱の BIGQUERY.md に書かれています。

接続情報は2つだけ

接続設定は BIGQUERY_PROJECT(プロジェクトID)と BIGQUERY_LOCATION(データセットのロケーション)の2つです。ロケーションは省略できます。接続情報が2項目だけなので、入口は軽い部類です。

READMEは、インストール前に端末の環境変数を設定する手順を示しています。

export BIGQUERY_PROJECT="my-gcp-project"
export BIGQUERY_LOCATION="asia-northeast1"

一方でClaude Code向けのマニフェスト(.claude-plugin/plugin.json)は、MCPサーバーの env を ${user_config.bigquery_project} のように、プラグインの設定項目(userConfig)から取る書き方です。設定項目は2つとも sensitive: false で、パスワードのような秘密情報を入れる項目はありません。ADCが認証を担うため、設定画面に秘密を入れる場面がない構成です。

どちらの値が優先されるかは、READMEにもマニフェストにも書かれていません。つながらないときは、片方だけを疑わず、設定画面と環境変数の両方にプロジェクトIDが入っているかを見るのが早道です。

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

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

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

claude plugin install bigquery-data-analytics@claude-plugins-official

マニフェストによると、プラグインが起動するMCPサーバーは npx -y @toolbox-sdk/server@1.10.0 --prebuilt bigquery --stdio の1つです。Toolboxのバージョンはマニフェストで固定されています。

導入後の棚卸しと負荷の測り方は、プラグインのコンテキスト消費を測る方法と導入済みプラグインの棚卸しが参考になります。

9つのツールは2つのグループに分かれる

MCP Toolboxのプリビルド設定には、9つのツールが定義されています。グループは data と analytics の2つで、search_catalog だけが両方に入っています。

役割は、ツールごとの説明文が短く示しています。analyze_contribution は多次元データで主要指標の変化への寄与を分析し、ask_data_insights は指定したテーブルの内容について分析や複雑な質問に答え、forecast は時系列データを予測します。

READMEの使用例は、データを探す依頼と、分析する依頼の2系統です。

• 「PyPIのダウンロードに関するテーブルを探して」
• 「bigquery-public-data.pypi.file_downloads で今月のダウンロード上位10パッケージを出して」
• 「同じテーブルで、urllib3 の2025年後半4か月のダウンロードを予測して」

最初の1回は、公開データセットで通し確認をするのが安全です。自分の課金プロジェクトから bigquery-public-data を引くことになるので、スキャン量は小さめのテーブルで確かめます。

同梱スキルは予測と異常検知をSQLで回す

プラグインに入っているスキルは、skills/bigquery-ai-ml の1つだけです。READMEの「Generating Skills Instead」節には、以前はツール由来のスキルが同梱されていたとあり、手で書かれたスキルはこの1つが残っています。

このスキルの指示は、はっきりしています。予測や異常検知のような機能では、専用ツールより execute_sql() で標準SQLのAI関数を呼ぶ方を優先する、というものです。つまり forecast ツールがあるのに、スキルが読み込まれた文脈ではSQLの AI.FORECAST が先に選ばれる設計です。

スキルが案内するAI関数は11個あります。

スキル本体に関数の構文は書かれていません。関数ごとに references/ 配下の参照ファイルがあり、SQLを作る前に必ず読むよう、スキルが指示しています。ファイル名を推測せず、表にある正確なパスだけを使うことも念押しされています。

予測を頼む場合、Claudeが読むはずの参照ファイルには、次の形の構文が載っています。

SELECT *
FROM AI.FORECAST(
  TABLE `project.dataset.table`,
  data_col => 'DATA_COL',
  timestamp_col => 'TIMESTAMP_COL',
  horizon => 30
)

これは参照ファイルの構文を縮めた例です。horizon や id_cols、confidence_level などは任意の引数です。実際に走るSQLは、依頼文とテーブルの列から変わります。

課金と書き込みを絞る環境変数

プラグインのマニフェストが渡す環境変数は2つだけですが、Toolboxのプリビルド設定は、もっと多くの変数を読みます。誤操作や課金を抑えるときに見る項目を挙げます。

設定ファイルには項目名と既定値があるだけで、各値の意味や、プラグイン経由の端末の環境変数がサーバーまで渡るかは説明されていません。使う前に、検証用のプロジェクトで値を入れ、結果が変わるかを確かめてください。たとえば BIGQUERY_READONLY を設定した端末で INSERT を頼み、拒否されるかを見る、という確認です。

環境変数に頼らない歯止めもあります。1つ目はIAMで、読み取りだけなら roles/bigquery.user に絞り、データの作成・更新に必要な roles/bigquery.dataEditor を渡さない構成です。この2つのロールは、同梱の BIGQUERY.md が権限エラー時の案内として挙げています。ただし BIGQUERY.md はGemini CLI向けの文脈ファイルで、Claude Code用のマニフェスト(plugin.json)からは参照されていません。ロールの目安として使えます。

2つ目はClaude Code側の権限です。プラグインが提供するサーバーのツール名は mcp__plugin_<プラグイン名>_<サーバー名>__* の形で書きます。この場合はプラグイン名が bigquery-data-analytics、サーバー名が bigquery です。

{
  "permissions": {
    "ask": ["mcp__plugin_bigquery-data-analytics_bigquery__*"]
  }
}

これは記法に当てはめた例です。execute_sql は任意のSQLを走らせるので、毎回確認つきにする価値が大きいツールです。個別のツール名で許可と拒否を分けるなら、/permissions で実際のツール名を確かめてから足します。

CLAUDE.mdに書く規約の例

接続できたら、BigQueryを触るときのルールを CLAUDE.md に置いておくと、依頼のたびに言わずに済みます。

## BigQuery の操作ルール
- 対象は analytics_prod プロジェクトの reporting データセットのみ
- クエリの実行前に、パーティション列で絞り込んだ SQL を提示する
- SELECT 以外の SQL は実行せず、文の提案にとどめる
- 予測や異常検知は AI.FORECAST / AI.DETECT_ANOMALIES を使う

規約はClaudeへの依頼文であり、強制力はありません。強制したい部分は、前の節の permissions とIAMのロールで受け持ちます。ログ分析の具体例は、GA4とBigQueryで作る週次レポートで通しの流れを見られます。

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

READMEのトラブルシューティング節は、Gemini CLIの表示を前提に書かれています。デバッグの案内は gemini --debug で、バイナリの ENOENT もGeminiの拡張機能フォルダを指すパスです。Claude Codeでは該当しない項目があります。

流用できるのは、認証の文言と接続切断の文言です。

兄弟プラグインとの違い

Google Cloudのデータ系では、同じ作りのプラグインが複数あります。接続先ごとに設定項目が変わる点が、いちばんの違いです。

AlloyDBプラグインは接続情報が8項目で、管理系のツールセットまで持ちます。Cloud SQL for PostgreSQLプラグインは接続情報が7項目で、うち必須は4つです。BigQueryはプロジェクトIDだけで済み、そのぶんデータセットやテーブルの指定は、依頼の文面かSQLの側で行います。

まとめ

導入は /plugin install bigquery-data-analytics@claude-plugins-official の1行で終わり、設定はプロジェクトIDだけです。

差が出るのは導入後です。execute_sql は毎回確認つきにし、読み取り専用ならIAMのロールも絞ります。予測と異常検知はスキルが案内するSQLの関数経由になるため、AI関数まで使うなら、Cloud Resource ConnectionとVertex AIの権限を先に整えておきます。ベータ版なので、まずは検証用のプロジェクトで使い始めるのが無理のない順序です。