BigQueryをClaudeで自然言語のまま分析する — 接続からレポート作成までの手順

BigQueryのデータをClaudeが直接読みに行く仕組み

BigQuery MCPサーバーは、GoogleがBigQuery API側で提供するリモートMCPサーバーです。エンドポイントはhttps://bigquery.googleapis.com/mcpで、トランスポートはStreamable HTTPです。BigQuery APIを有効にした時点で使えるようになります。Claude、Gemini CLI、ChatGPTなど複数のAIアプリから同じエンドポイントに接続できます。

接続すると、Claudeはデータセット一覧の取得やSQL実行、スキーマ確認をツール呼び出しとして行います。自分でSQLを書く必要はありません。「先月の注文データから上位顧客を教えて」のように話しかけるだけで、Claudeがテーブルを探し、クエリを組み立て、結果を要約します。

前提はGoogle Cloudプロジェクトと、次節のIAMロール3つです。課金を有効にしなくてもBigQueryサンドボックスの範囲で試せます。

事前準備 — IAMロールを3つ割り当てる

使うプロジェクトで、次の3つのIAMロールが必要です。管理者に付与を依頼するか、自分がオーナー権限を持つプロジェクトで設定します。

新規プロジェクトではBigQuery APIが自動で有効です。既存プロジェクトを使う場合は、Google CloudコンソールでAPIが有効か先に確かめます。組織でカスタムロールを使っているなら、上の3権限が含まれているかを見れば足ります。ただしタスクによっては、BigQueryの追加権限が別途必要になります。

Googleは、エージェント用に人間とは別のIDを作ることも勧めています。リソースへのアクセスを制御・監視しやすくするためです。認証に使うOAuthスコープはhttps://www.googleapis.com/auth/bigqueryの1つで、BigQueryのデータの閲覧と管理を含みます。

ステップ1: OAuthクライアントを発行してClaudeに接続する

BigQuery MCPサーバーはOAuth 2.0とIAMで認証します。Googleの手順では、Claude.ai・Claude Desktop・Claude Codeのどれでも、自分でOAuthクライアントIDとシークレットを発行してからコネクタに入力します。

クライアントを発行したら、使うClaudeの形態ごとにカスタムコネクタを登録します。コネクタの種類や追加方法の全体像はClaude Connectorsとはにまとめています。

Claude.ai / Claude Desktopの場合: 「Customize」→「Connectors」からカスタムコネクタを追加します。Team / Enterpriseでは、「Organization settings」→「Connectors」からOwnerが追加します。サーバーURLにはhttps://bigquery.googleapis.com/mcpを入れます。認証のOAuth clientで「Use your own OAuth client」を選び、クライアントIDとシークレットを入力します。

Claude Codeの場合: CLIからサーバーを登録します。OAuthクライアントIDを渡すオプションは、v2.1.287のclaude mcp add --helpに次のとおり並びます。

claude mcp add --help

  --callback-port <port>       Fixed port for OAuth callback (for servers
                               requiring pre-registered redirect URIs)
  --client-id <clientId>       OAuth client ID for HTTP/SSE servers
  --client-secret              Prompt for OAuth client secret (or set
                               MCP_CLIENT_SECRET env var)

発行したIDとシークレットを渡し、コールバックのポートを固定して登録します。ポートは空いている任意の番号でよく、ここでは8080を例にします。Googleのクライアントに登録するURIのポートと必ず揃えます。--client-secretは値を取らず、実行するとシークレットの入力を求められます。

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID --client-secret \
  --callback-port 8080 \
  bigquery https://bigquery.googleapis.com/mcp

登録後、セッション内で/mcpを実行するとブラウザでOAuth認証が始まります。認証が済むと、claude mcp listに✔ Connectedと表示されます。claude mcp listは登録済みの各サーバーへ接続して状態を確かめるコマンドで、未認証なら! Needs authenticationと出ます。

リダイレクトURIには、2つのページで食い違いがあります。Googleの手順は、Claude Codeでもhttps://claude.ai/api/mcp/auth_callbackだけを登録させます。一方、Claude Codeのドキュメントでは、OAuthの戻り先に既定でランダムな空きポートを使います。事前登録のURIが必要なサーバーには--callback-portでポートを固定し、http://localhost:PORT/callbackの形で登録する、という説明です。

そこでGoogleのクライアントには、2つのURIを「+ Add URI」から登録します。1つはGoogleの手順のhttps://claude.ai/api/mcp/auth_callbackです。もう1つはClaude Codeの説明のhttp://localhost:ポート番号/callback(上の例ならhttp://localhost:8080/callback)です。認証でリダイレクトURIの不一致が出たら、まずここを見ます。v2.1.229はhttp://127.0.0.1:PORT/callbackの形で送ってしまい不一致になる場合があり、v2.1.231でlocalhostの形に戻っています。

ステップ2: 自然言語でデータを問い合わせる

接続できたら、Claudeに話しかけるだけでBigQueryのデータへアクセスできます。プロジェクトIDやデータセット名を伝えると、Claudeがテーブル構造を確認してからクエリを組み立てます。

背後で動くツールは9つです。このうち6つは、呼ぶAPIメソッドとクォータが次の表のとおり決まっています。

残るget_query_results・cancel_job・get_jobは、ジョブの結果取得・中止・状態確認に使います。

「データセット一覧」はlist系、「スキーマ確認」はget系、「集計」はexecute系、という対応です。BigQuery MCPサーバー自体にクォータはなく、呼び出し回数の上限もありません。ただし、各ツールが呼ぶAPIメソッドのクォータには従います。重い集計を連発したときに効いてくるのは、クエリジョブ側のクォータです。

myprojectのデータセット一覧を見せて

sales_dataデータセットのordersテーブルから、直近30日で購入額が多い上位10社を教えて

asia-northeast1リージョンでMCP経由で実行したクエリを、goog-mcp-server:trueのタグで絞り込んで一覧にして

最後の例のように、MCP経由のジョブはgoog-mcp-server:trueというタグで見分けられます。Googleのサンプルプロンプトにある切り口で、監査ログを追うときに使えます。SQLそのものをClaude Codeに書かせるときの注意点はClaude Code SQLと正規表現を安全に書かせる勘所にまとめています。

ステップ3: 予測やレポート作成まで任せる

BigQueryの予測関数AI.FORECASTは、execute_sql_readonlyでもSELECT文として書けます。AI.DETECT_ANOMALIES・AI.KEY_DRIVERS・AI.CLASSIFY・AI.GENERATEといった組み込みのAI/ML関数も同じです。生の行を取り出さず、ウェアハウス内で計算するための関数です。Googleのサンプルプロンプトには、予測(forecast)を呼ぶ例も入っています。対象テーブルとデータ列、時間軸の列を伝え、上位10件の予測値を出させる形です。

sales.dataset.revenueテーブルで、revenue列を対象にdate列を時間軸として将来の売上を予測して。上位10件の予測値を見せて

会話を続けて「表にまとめて」「先週との差分だけ抜き出して」と頼めば、SQLを書き直す代わりに自然言語で修正を重ねられます。GA4のエクスポートデータで週次レポートを回す例はGA4のBigQueryをClaudeで分析する手順にあります。

Googleが挙げる想定用途は、レポート作成だけではありません。BigQueryのデータから得た知見をきっかけにIssueを作ったりメールを起票したりするワークフロー、そして専用のエージェント指示文を使った対話型の分析です。分析結果を人間が読むレポートで終わらせず、後続の業務アクションにつなげる使い方も想定されています。

execute_sqlとexecute_sql_readonlyの使い分け

読み取り専用でないツールはexecute_sqlだけです。分析用途なら、まずexecute_sql_readonlyから始めます。

execute_sqlを使わせたくない場合、制限の手段は2つあります。1つはGoogle Cloud側のdenyポリシーで、公式ドキュメントは読み書き両用のMCPツールの使用を制限するポリシーを作る方法を案内しています。denyポリシーの条件には、次の4つを使えます。読み取り専用属性(tool.isReadOnly)、サービス名(resource.service)、ツール名(tool.name)です。残る1つがOAuthクライアントID(request.auth.oauth.client_id)です。OAuthクライアントIDはallowポリシーでは使えません。これらの属性が評価されるのは、mcp.tools.call権限のときだけです。

もう1つはClaude Code側です。settings.jsonのpermissions.denyにmcp__bigquery__execute_sqlを入れると、このツールの呼び出しをブロックできます。ルール名はmcp__<サーバー名>__<ツール名>の形で、サーバー名はclaude mcp addで付けたbigqueryです。サーバー名を変えて登録したなら、ルールの名前も揃えます。

{
  "permissions": {
    "deny": ["mcp__bigquery__execute_sql"]
  }
}

Google側のdenyポリシーは、適用したプロジェクトで対象に含めたプリンシパルに効き、Claude Code側の設定はその設定ファイルを使う環境にだけ効きます。分析専用のチームなら、両方を掛けておく構成が現実的です。データベース系MCPサーバーを読み取り専用から始める設計はMCPからデータベースに接続する方法でも扱っています。

専用のツール集合(Toolset)を指して接続する

ツールが多すぎるとエージェントの負荷になるため、GoogleはMCPサーバーのツールの一部だけを持つツール集合(toolset)を使えるようにしています。ツール集合は固有のエンドポイントを持ち、MCP設定ではサーバーのエンドポイントの代わりにそのエンドポイントを指定します。Googleの説明では、60個以上のツールを持つサーバーでも、15個のツールに絞った集合を使えば負荷をかけずに使えます。

BigQueryのツール一覧は、tools/listのHTTPリクエストを直接送って取得できます。このメソッドに認証は要りません。リクエスト先はhttps://bigquery.googleapis.com/に続けて、ツール集合ごとのエンドポイントを付けた形です。ドキュメントの例はmcp/toolset-nameです。

よくあるつまずき

クエリが20秒(既定の同期タイムアウトで、timeout_msで変えられます)以内に終わると、job_complete: trueと結果の行が直接返ります。それより長くかかるとjob_complete: falseとjob_idが返るので、get_query_resultsにjob_idを渡し、job_complete: trueになるまで取得します。途中で止めたいときはcancel_jobを使い、サーバー側で強制的に打ち切りたいときはjob_timeout_msを指定します。

実行制限は、次の3点が重なります。

3分で切れたときは、集計範囲を絞ります。重いバッチ処理はBigQueryコンソールやbq CLIに切り替えます。3,000行で切れる結果は、全件が必要な作業に向きません。集計や上位N件の抽出を前提に組みます。

IAMロールが1つ欠けて動かない: 3つのうち1つでも欠ければ、操作は通りません。たとえば「MCP Tool User」だけではbigquery.jobs.createが足りません。MCPツールの呼び出しでは、mcp.tools.callがあっても基になるBigQueryの権限(たとえばbigquery.datasets.get)がなければ失敗し、逆の場合も失敗します。エラーが出たら、3つのロールと権限を照らして確認します。

Claude Codeでclaude mcp listが未認証を示す: ! Needs authenticationと出たら、セッション内で/mcpを開いて認証をやり直します。

まとめ

塞ぐ層は、誰に効かせたいかで変わります。チーム全員ならGoogle側のdenyポリシー、自分のClaude Code環境だけならpermissions.denyが受け持ち、分析専用のチームには両方を掛けられます。指標定義を揃えたうえで問い合わせたい場合はdbt Semantic Layerの使い方が近い選択肢です。