Claude Media
Claude BigQuery連携 — Google公式MCPサーバーで自然言語クエリーを投げる
Claude CodeMCPClaude連携チュートリアル

Claude BigQuery連携 — Google公式MCPサーバーで自然言語クエリーを投げる

GoogleはBigQuery用のマネージドMCPサーバーを公式提供しています。20秒の同期待ちや読み取り専用の止め方まで、Claude Codeへの接続手順を実機出力つきで確認します。

読了目安 約14分

Google CloudはBigQuery向けのMCP(Model Context Protocol)サーバーを、Googleが自社で運用するマネージドサービスとして公式提供しています。エンドポイントはbigquery.googleapis.com/mcpで、Googleのドキュメント自身が接続先クライアントの例としてClaudeを名指ししています。サーバーを自分でホストする必要はなく、BigQuery APIを有効にしたプロジェクトでIAMの権限を整えれば接続できます。

ここでは接続前の権限確認から、Claude Codeへの登録、9つのツールの役割、実際につまずきやすい制限までを順に扱います。

接続前に確認する権限とAPI

BigQuery MCPサーバーは、BigQuery APIを有効にすると使えるようになります。新規プロジェクトではAPIが自動で有効です。課金を有効にしなくても、BigQueryのサンドボックスの範囲で同じ手順は動きます。ただし、課金アカウントが付いたプロジェクトでサンドボックスを使うなら、そのプロジェクトの課金を無効にする必要があります。

使うプロジェクトでは、次の3つのIAMロールが必要です。

ロール用途対応する権限
roles/mcp.toolUser用途MCPツールの呼び出し自体を許可対応する権限mcp.tools.call
roles/bigquery.jobUser用途BigQueryジョブの実行対応する権限bigquery.jobs.create
roles/bigquery.dataViewer用途BigQueryデータの参照対応する権限bigquery.tables.getData

管理者に3つのロールを付与してもらうのが最初のステップです。roles/bigquery.jobUserが欠けると、クエリーは組み立てられても、ジョブ実行の段階で失敗します。カスタムロールなど、ほかのロールで同じ権限を組み合わせても構いません。タスクによっては追加の権限が必要になる場合もあります。

認証はOAuth 2.0とIAMの組み合わせで、Googleが挙げる認証スコープはhttps://www.googleapis.com/auth/bigqueryです。Googleはエージェント専用のIDを別に作ることを推奨しており、リソースへのアクセスを人間の操作と分けて管理・監視できます。

Claude Codeへの登録から認証まで

BigQuery MCPサーバーはStreamable HTTPのリモートサーバーです。Claude Codeでは--transport httpで追加します。

claude mcp add --transport http bigquery https://bigquery.googleapis.com/mcp

追加しただけでは認証が済んでいません。Claude Codeの中で/mcpを実行し、OAuthのサインインを完了させます。

/mcp

ブラウザが自動で開かなければ、表示されたURLを手動で開きます。認証後にリダイレクトが接続エラーになったときは、ブラウザのアドレスバーにあるコールバックURL全体をClaude Code側のURL入力欄に貼ります。トークンは安全に保存され、自動で更新されます。保存済みのリフレッシュトークンが拒否された場合は、/mcpで「Re-authenticate」を選んで入り直します。

登録の実際の結果(v2.1.285で確認)

claude mcp addの既定のスコープはlocalで、設定はそのユーザーの~/.claude.jsonに入り、チームには共有されません。チームで同じ設定を共有したいときは--scope projectを付けます。作業用の空ディレクトリで-s projectを付けて実行すると、次のように出力されました。

claude mcp add --transport http -s project bigquery https://bigquery.googleapis.com/mcp
Added HTTP MCP server bigquery with URL: https://bigquery.googleapis.com/mcp to project config

プロジェクトのルートに作られた.mcp.jsonの中身は次のとおりです。

{
  "mcpServers": {
    "bigquery": {
      "type": "http",
      "url": "https://bigquery.googleapis.com/mcp"
    }
  }
}

プロジェクトスコープのサーバーは、最初は承認待ち(Pending approval)として扱われ、claudeを対話的に起動して承認するまで接続されません。同じサーバー名を別スコープに別のエンドポイントで定義すると、OAuthのサインインはエンドポイントごとに別管理になるため、プロジェクトごとに入り直しが必要になる場合があります。claude mcp addのオプションやスコープの詳細はClaude Code MCP設定ガイドにあります。

Claude.aiやCoworkから接続する場合

Free・Pro・Maxプランなら、「Customize > Connectors」の「Add custom connector」からエンドポイントURLを入力します。Freeプランで追加できるカスタムコネクタは1つです。TeamやEnterpriseプランでは、通常のメンバーは自分で追加できません。Ownerが組織設定の「Connectors」から追加し、各メンバーが自分のアカウントで「Connect」を押して認証します。Enterpriseでは、組織のライブラリ管理を含むカスタムロールを持つメンバーも追加できます。

9つのツールは何をするか

BigQuery MCPのリファレンスに載っているツールは9つです。書き込みができるのはexecute_sqlだけです。

ツール

BigQuery MCPの9つのツール

  • 探索する(4つ)

    list_dataset_idsとlist_table_idsで一覧を取り、get_dataset_infoとget_table_infoでメタデータを読みます。スキーマの探索はこの4つで済みます。

  • SQLを実行する(2つ)

    execute_sql_readonlyはSELECTだけを許可します。execute_sqlはINSERT・UPDATE・DELETE・CREATE・DROPまで通り、リファレンスも「可能ならexecute_sql_readonlyを優先する」と書いています。

  • ジョブを扱う(3つ)

    get_query_resultsは長いクエリーの結果を取りに行き、続きの行のページ送りにも使います。cancel_jobで実行中のジョブを止め、get_jobで状態を確認します。

execute_sql_readonlyのツール説明には、予測・異常検知・要因分析・分類といった作業は、行を手元に持ち出さずにAI.FORECAST・AI.DETECT_ANOMALIES・AI.KEY_DRIVERS・AI.CLASSIFY・AI.GENERATEといったBigQueryのAI/ML関数でウェアハウス内で計算するよう書かれています。つまりClaudeは、Pythonで集計し直すのでなく、これらの関数を使うSQLを組み立てるよう誘導されています。

BigQueryを介さずGA4のレポートを直接問い合わせたいときは、Claude CodeにGA4のMCPサーバーを繋ぐ手順を参照してください。

遅いクエリーで何が起きるか

制限は「3分」と「3,000行」が有名ですが、ツール説明を読むともう1つの時間が絡みます。実行ツールには同期で待つ時間があり、既定は20,000ミリ秒(20秒)です。

制限

時間と行数の上限

  • 同期待ちの既定

    20秒

    timeout_msで変更できる

  • 処理時間の上限

    3分

    既定。超えると自動でキャンセルされる

  • 結果の行数

    3,000行

    1回のクエリー結果の最大

20秒以内に終わるクエリーは、結果の行がそのまま返ります。20秒を超えたときは、実行ツールがjob_complete: falseとjob_idを返します。ここから先はget_query_resultsにjob_idを渡してjob_complete: trueになるまで待つか、cancel_jobで止めます。job_timeout_msを指定すると、サーバー側でジョブを強制終了させる時間も決められます。

Claudeが「結果が返ってこない」ように見えるときは、この2段階の待ち時間の途中にいる可能性があります。その他の制限は次のとおりです。

  • execute_sql・execute_sql_readonlyとも、Google Driveの外部テーブルへのクエリーには対応しない
  • execute_sql_readonlyはDML文・DDL文・Python UDFを実行できない
  • execute_sql_readonlyはGraph Query Language(GQL)を使うクエリーにも対応しない

大量データの集計や長時間の分析クエリーをそのまま投げると、行数上限や時間制限に当たります。集計はBigQuery側でビューやマテリアライズドビューにしておき、MCP経由ではその結果を読むだけにする分担が現実的です。権限設計とリスクの考え方はMCPセキュリティガイドにまとめています。

読み取り専用に絞りたいとき

書き込みを伴うのはexecute_sqlだけなので、読み取り専用に統一したいなら、このツールを拒否ポリシーで止めます。Googleの説明では、IAMの拒否ポリシー・許可ポリシーは、プリンシパル、読み取り専用かどうかといったツールの属性、サービス名やツール名、アプリケーションのOAuthクライアントIDを条件にできます。

Claude Code側だけで止めるなら、permissions.denyにmcp__bigquery__execute_sqlを入れて呼び出しを拒否する手段もあります。Google側のポリシーとは別に効くクライアント側の制限です。

拒否ポリシーを置かない個人利用では、まず付けるロールをbigquery.dataViewerとジョブ実行権限までに絞る方法があります。ただし、この構成でexecute_sqlが実際にどう失敗するかは、Googleのドキュメントに書かれていません。書き込みを確実に止める手段として案内されているのは、拒否ポリシーです。

curlでツール一覧を確認する — Googleの2ページで例が違う

認証なしで呼べるtools/listで、サーバーが公開しているツールを確認できます。ただし、Googleの2つのページで、curlの例が異なります。

リファレンスのページは、content-typeとacceptのヘッダーだけを付けた、簡素な例です。

curl --location 'https://bigquery.googleapis.com/mcp' \
  --header 'content-type: application/json' \
  --header 'accept: application/json, text/event-stream' \
  --data '{ "method": "tools/list", "jsonrpc": "2.0", "id": 1 }'

一方、使い方のページは、MCPの2026-07-28版に合わせた形です。MCP-Protocol-VersionとMcp-Method: tools/listのヘッダーを付け、リクエスト本体のparams._metaにプロトコルのバージョンとクライアントの能力を入れます。この版ではinitializeのやり取りやMcp-Session-Idが不要になり、各リクエストが自己完結する設計に変わっています。

使い方ページのエンドポイントはhttps://bigquery.googleapis.com/TOOLSET_ENDPOINTの形で、BigQueryならmcp/toolset-nameのようになると説明されています。ツールの一部だけを独自のエンドポイントで公開する仕組みで、Acceptヘッダーもapplication/jsonのみの例です。

自分で叩いてみて通らないときは、リファレンス側の簡素な例か、使い方ページの完全な形かを切り替えて試す価値があります。MCP Inspectorを使えば、コマンドラインを経由せずに同じ一覧をGUIで確認することもできます。本記事では実際のリクエストは送っていないため、どちらが現行のサーバーで通るかは確認できていません。

MCP経由とbq CLIの使い分け

BigQueryへのアクセス手段はMCP経由だけではありません。Googleは、ローカルのMCPサーバーも別に用意しています。カスタムのパラメーター化SQLをツールとして作りたいときや、プロジェクトでリモートMCPサーバーを有効化・利用する権限がないときの選択肢です。

スケジュール実行や権限管理、リザベーションの管理のような高度な操作は、Google Cloud CLIのリモートMCPサーバーにあるrun_bq_commandツールが受け持つと説明されています。

くらべる

Claudeから使うときの向き不向き

対話的な探索・分析

BigQuery MCP

スキーマを確認しながら、自然言語で対話的にクエリーを組み立てる作業に向きます。予測や異常検知も、AI/ML関数を使うSQLとして会話の中で試せます。

定型・大量のデータ

bq CLI・クライアントライブラリ

定期実行するバッチ集計や、3,000行を超える全件データの取得に向きます。MCP経由の時間・行数の制限を受けないためです。

クエリー課金と、呼び出しの追跡

BigQueryはオンデマンド料金の場合、スキャンしたバイト数で課金されます。MCP経由ではClaudeが自然言語からSQLを組み立てるので、自分でSQLを書くとき以上に、意図せず広い範囲をスキャンするクエリーが走る可能性を意識する必要があります。「全期間のデータを集計して」のような曖昧な指示は、その典型です。

execute_sqlのツール説明によると、クエリーはproject_idで指定したプロジェクトに課金されます。BigQuery MCPサーバー自体には独自のクォータがなく、呼び出し回数の制限もありません。ただし、ツールが内部で呼ぶAPI(jobs.Queryやtables.getなど)のクォータは通常どおり適用されます。

対策は、プロンプトの中で対象期間やパーティション列を具体的に指定することです。パーティション化されたテーブルなら、日付範囲を明示するだけでスキャン量を抑えられます。

MCP経由で実行されたクエリーを後から追いたいときは、ジョブのラベルが手掛かりになります。execute_sqlとexecute_sql_readonlyのどちらで実行したクエリーにも、自動でgoog-mcp-server: trueというラベルが付きます。Googleのサンプルプロンプトも、このラベルでMCP経由のジョブを見分ける使い方を挙げています。Claude自身に「このリージョンでMCP経由に実行したクエリーを探して」と頼む形です。

使えるプロンプトの例

Googleが挙げているサンプルプロンプトには、次のようなものがあります。

  • 「プロジェクトPROJECT_IDのデータセット一覧を教えて」
  • 「DATASET_IDの中で受注量の多い注文を上位順に並べて、該当するテーブルとスキーマを特定した上で見せて」
  • 「テーブルTABLE_IDについて、COLUMN_NAMEを対象カラムとした将来予測を作って、上位10件を見せて」

3つ目は、BigQueryの予測機能(AI.FORECAST)を呼び出す型の依頼です。実際のAI.FORECASTの呼び出しは、execute_sql_readonlyのツール説明にdata_col・timestamp_col・id_cols・horizonといった引数を取る例が載っています。

Search ConsoleのデータをBigQuery経由で読む具体例は、Search ConsoleのBigQueryをClaudeで分析する手順にあります。読み取り専用のデータベース接続の設計全般は、Claude CodeでMCPからデータベースに接続する方法でも扱っています。BigQuery以外のデータベースと比べたい場合の参考になります。

まとめ — どこから始めるか

まずはロール3種の付与を管理者に依頼し、execute_sql_readonlyだけで運用する形から始めるのが無理のない入口です。書き込みが必要になったとき、拒否ポリシーの解除を含めてexecute_sqlを個別に検討します。AWSやAzure中心の環境で同様の分析基盤を使うなら、Databricks MCPサーバーも選択肢になります。

よくある質問

Model Armorとは何ですか、設定は必須ですか

Model Armorは、LLMへのプロンプトとレスポンスを走査して、悪意のある入力や機密データの流出などを防ぐGoogle Cloudのサービスです。BigQuery MCPサーバーを使うために必須ではなく、有効にするかどうかは任意です。有効にするときは、次の2点に注意します。

  • ログを有効にしたModel Armorは、ペイロード全体をログに残すため、機密情報が漏れる可能性がある
  • MCPの通信が自然言語のデータを運ばないなら、プロンプトインジェクションとジェイルブレイクのフィルターは有効にしないよう、Googleが勧めている
この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →