BigQuery Data Platform

BigQuery MCP

Google BigQuery 上で動作する読み取り専用のModel Context Protocolサーバーです。AI クライアント（Claude Code、Claude Desktop など）が、スキーマを調べてSELECTクエリを実行し、自然言語でのデータに関する質問に回答できるようにします。

自然言語から SQL への変換は AI が行います。このサーバーは、ご自身の Google 認証情報を使用して BigQuery に対して安全にクエリを実行するだけです。

• ドキュメント: https://debilla.github.io/bigquery-mcp/
• リポジトリ: https://github.com/deBilla/bigquery-mcp
• PyPI: data-platform-mcp
• MCP レジストリ: mcp-name: io.github.deBilla/data-platform-mcp

---

提供するツール

ツール	目的	費用
list_datasets	プロジェクト内のデータセットを一覧表示します	無料
list_tables	データセット内のテーブル／ビューを一覧表示します	無料
get_table_schema	列（ネストされたパスを展開）、パーティショニング、サイズ、行数を取得します	無料
check_table_freshness	各テーブルが最後に書き込まれた時刻を確認し、古いデータソースを検出します	無料
list_environments	設定されている BigQuery 環境とデフォルト環境を確認します	無料
list_scheduled_queries	テーブルに書き込むスケジュール済みクエリと、無効化または失敗しているかを確認します	無料
get_scheduled_query	1 つのクエリの SQL、出力先、最近の実行状況を取得します	無料
list_code_assets	BigQuery Studio のノートブック、保存済みクエリ、データキャンバスを一覧表示します	無料
get_code_asset	1 つのノートブックまたは保存済みクエリの本文を取得します（ノートブックの出力は除外されます）	無料
find_code_assets_using_table	どのノートブック／保存済みクエリがテーブルを読み取るかを確認します	割り当て量を消費。金銭的費用なし
list_notebook_schedules	スケジュール済みの Colab ノートブックと、最近失敗した実行回数を一覧表示します	無料
list_notebook_runs	すべてのスケジュールにわたる個々のノートブック実行を一覧表示します（デフォルトでは失敗のみ）	無料
get_notebook_schedule	1 つのスケジュールの cron、ノートブック、最近のエラーを取得します	無料
run_query	検証済みの読み取り専用SELECTを実行し、行を返します	データをスキャン

費用がかかるのはrun_queryだけなので、まずは検出ツールを使ってください。特定のよくある間違いを防ぐためのツールが 2 つあります。

• get_table_schemaは列名ではなく、テーブルのメタデータからパーティショニングを報告します。 partition_date列があるテーブルでも、パーティション分割されているとは限りません。その場合、WHERE句を指定してもスキャン量は減らず、クエリのたびにテーブル全体が読み取られます。テーブルが大きい場合、応答でこの点を明示します。
• check_table_freshnessは、削除されずに書き込みが止まったテーブルを見つけます。 こうしたテーブルはエラーではなく古いデータを返します。これは誰も気づかないまま発生する障害です。
• find_code_assets_using_tableは、もう半分の情報を提供します。 スケジュール済みクエリのツールはテーブルに何が書き込むかを示しますが、このツールは何がテーブルを読み取るかを示します。スキーマを変更する前に確認すべき情報です。また、無料ではない唯一の検出ツールです。対象とするアセットをすべて開くため、Dataform の読み取り割り当て量を消費します。そのため上限が設定されており、プロジェクトのどの範囲まで実際に確認したかを報告します。結果が示すのはスキャンしたアセットについての証拠であり、ほかにテーブルを使用するものがないという証明ではありません。読み取れなかったアセットは、見落としとして数えるのではなく、別途一覧表示されます。
• list_scheduled_queriesは理由を示します。 テーブルが古くなっている場合、通常はスケジュール済みクエリが無効化されているか、失敗しています。この情報は別の API（BigQuery Data Transfer）にあり、roles/bigquerydatatransfer.viewerが必要です。このロールがない場合、2 つのツールはそのロール名を含むエラーを返しますが、それ以外は通常どおり動作します。ほとんどのスケジュール済みクエリは DDL で書き込むため出力先を宣言しません。そのため、SQL から出力先を読み取り、ヒューリスティックであることを明記したwrites_to_from_sqlとして報告します。

BigQuery Studio のノートブックと保存済みクエリ

これらは BigQuery のリソースではありません。BigQuery Studio では各コードアセットが 1 つのファイルを格納する Dataform リポジトリとして保存されます。そのため、BigQuery と Data Transfer Service に加えて、3 つ目の API と権限である roles/dataform.viewer が必要です。この権限がない場合、3 つのツールはロール名を示すエラーを返しますが、その他は通常どおり動作します。また、Dataform の UI には表示されないため、コンソールを見ても保存場所の手がかりはありません。

設定する前に、この保存方法について知っておくべき点が 2 つあります。

• コードアセットはリージョン単位で、データセットのリージョンとは異なります。 Dataform はマルチリージョンを受け付けないため、データセットが US にあるプラットフォームでは、ノートブックは us-central1 のような場所に保存されます。設定は不要です。 location がマルチリージョンの場合、サーバーはその中のリージョンを調べ、アセットがあるリージョンを使用して、その旨を返します。マルチリージョンをそのまま引き継ぐことはできません。そうすると、単に失敗する可能性が高いのではなく、確実に失敗するためです。調査をスキップするには、code_asset_location（または BQ_CODE_ASSET_LOCATION）を指定してください。明示的に指定した値が再検証されることはないため、値が誤っているとエラーではなく空のリストが返されます。すべての結果には、読み取りに使用したロケーションが含まれます。

• ノートブックの本文の大半は出力です。 実際のノートブック 52 個を調べたところ、セル出力はバイト数の 77% を占めていました。あるファイルはコードが 80 KB なのに、サイズは 1.44 MB でした。返却前に出力は削除され、削減量も報告されるため、欠けているものがロジックではなく描画済みのグラフだと確認できます。

読み取りには同時実行数ではなくデータ量に基づくクォータ制限があり、クォータは数十秒かけて回復します。クォータ超過時はバックオフを伴って再試行されます。超過が続く場合は、失敗としてではなく、少し待ってから再試行するよう通知されます。

---

スケジュール設定された Colab ノートブック

BigQuery Studio のノートブックにはスケジュールを設定できますが、スケジュール実行の作業は監視されないままになりがちです。実行結果がどこにも報告されないため、ノートブックが何週間も毎晩失敗し続けても、テーブルの更新がいつの間にか止まったことだけが兆候になります。この仕組みを構築したプラットフォームでは、7,061 件の実行のうち 354 件が失敗していましたが、そのことは何も可視化されていませんでした。

ひとつの質問に答えるには 3 つのリソースを結合する必要があり、これが状況を把握しにくくしていた主な理由です。スケジュールは Vertex AI の Schedule（cron、タイムゾーン、一時停止の有無）です。各実行は NotebookExecutionJob です。ノートブックは、list_code_assets が一覧表示するものと同じ Dataform コードアセットです。そのため、失敗したスケジュールから、失敗したコードの get_code_asset に直接たどり着けます。つまり 4 つ目の API と、4 つ目の権限 roles/aiplatform.viewer が必要です。この権限がない場合、3 つのツールはロール名を示すエラーを返しますが、それ以外は通常どおり動作します。新たな依存関係はありません。2 つの一覧取得エンドポイントのために google-cloud-aiplatform を追加するのではなく、REST 経由で Vertex AI と通信します。

表示される情報を信頼する前に、知っておくべきことが 3 つあります。

• ノートブックが失敗していても、スケジュール自体は正常と報告します。 稼働中の 49 件のスケジュールはすべて、直近のスケジュール実行を OK と報告しています。これには、直前の 79 回の実行が失敗していたものも含まれます。OK が意味するのは、スケジューラーがジョブの起動に成功したということであり、ノートブックが実行されたということではありません。このフィールドはコンソールで最初に表示されるものであり、まさにこれが問題の見過ごされた原因です。そのため、ここでの正常性は常に実行ジョブから算出し、スケジュール自体のステータスを正常性として報告することはありません。一方、PAUSED のスケジュールは、ノートブックが書き込むテーブルの更新が止まる最もよくある原因です。

• 実行結果はサーバー側でフィルタリングできません。 Vertex AI は jobState フィルターを拒否し、ページの上限は 100 件です。そのため、「失敗したものを見せて」という場合は、ページを読み込み、ローカルでフィルタリングします。実行は新しい順に並んでいるため、対象期間を限定すれば効率よく取得できます。デフォルトが 30 日の lookback_days（月次スケジュールでも少なくとも 1 回の実行が表示される期間）を使うと、1 年分の履歴をスキャンせずに取得を打ち切れます。30 日で API 呼び出しは約 7 回、90 日で約 23 回です。

• 実行は、それを作成したスケジュールが削除された後も残ります。 スケジュールの編集には、削除して再作成するのが一般的です。そのため、稼働中の 7,061 件の実行が参照しているスケジュールは 75 件ですが、現在も存在するのは 49 件だけです。これらの実行は実際のものであり、失敗も集計対象になるため、削除せず (schedule no longer exists) と表示します。同じ理由から、表示名は一意とは限りません。稼働中のスケジュール 2 件が同じ表示名を共有していました。そのため、名前が曖昧な場合は候補と ID を列挙するエラーになり、最初に一致したものを黙って選ぶことはありません。

data-platform-mcp doctor は、読み取り可能なスケジュール数、一時停止中の数、直近 1 週間に失敗した数を報告します。

---

環境

1 つのサーバーで、ウェアハウスとそのステージング用コピー、または同じプロジェクトの 2 つのリージョンなど、複数の対象について質問できます。すべてのツールには省略可能な environment があり、省略するとデフォルトが使われます。

# ~/.config/data-platform-mcp/config.toml
default_environment = "warehouse"

[environments.warehouse]
project = "my-data-platform"
impersonate = "[email protected]"
dataset_allowlist = ["sales", "events"]

[environments.central]          # same project, different region
project = "my-data-platform"
location = "us-central1"

すべての設定については config.toml.example をご覧ください。または、同じ構造を JSON として BQ_MCP_ENVIRONMENTS に設定します。単一の BQ_PROJECT も引き続きそのまま使用できます。その場合は default という名前の環境になります。

環境は、環境名、エイリアス、組み込みの短縮名（prod、stg、dev、live）、またはプロジェクト ID で指定できます。不明な名前が指定された場合は、有効な選択肢を示すエラーになります。デフォルト環境に黙ってフォールバックすることはありません。ステージングから本番環境についての質問に答えてしまうようなタイプミスが、返答からはわからないためです。すべての結果には、使用した環境が示されます。

ここでは、リージョンの違いが特に重要です。BigQuery はロケーションをまたいだクエリを実行できませんが、ロケーションを指定しない場合に出るエラーは、テーブルが存在しないかのように見えます。ロケーションごとに環境を 1 つ設定してください。doctor は各データセットのロケーションを報告します。

---

ID のプロパティとしての読み取り専用

SELECT のみを許可するガードと readOnlyHint アノテーションは、このコードに関する約束です。サーバーに、roles/bigquery.jobUser とデータセット単位の roles/bigquery.dataViewer だけを持つサービスアカウントを指定すれば、それは認証情報によって保証される事実になります。コードが何をするか、またご自身のロールで何が許可されているかに関係なく、IAM によって強制されます。

data-platform-mcp setup --project my-data-platform --datasets sales,events

アカウントを作成し、この 2 つのロールを付与して、サーバーがそのアカウントになりすませるよう、アカウントに対する roles/iam.serviceAccountTokenCreator を付与します。まずコマンドを確認するには --dry-run を追加してください。安全に再実行できます。

--datasets を指定すると、データセットの許可リストはこのプロセス内の if 文ではなく、Google によって強制される権限付与になります。

---

macOS のセットアップ

Terminal.app は Xcode ではありません。 すべての Mac に付属しています。付属していないのは Xcode Command Line Tools で、アナリストのノートパソコンには通常、これも Homebrew もありません。ここで必要になるものはありません。ただし、誤って実行してしまいやすいので注意が必要です。git、make、clang、標準の /usr/bin/python3 は、そのツール群を起動するためのスタブです。これらを実行すると、約 1 GB の開発ツールをインストールするためのシステムダイアログが表示されます。

以下のコマンドはどれも、それらを呼び出しません。どちらのインストールも自己完結しているため、macOS に標準で備わっているユーティリティ、curl、tar、sh、uname だけを使います。

インストール	ほかに何も必要ない理由
uv	スタンドアロンのバイナリです。インストーラーが Python に言及することはなく、サーバーの実行に必要な Python も自らダウンロードします。
Google Cloud CLI	macOS 用の tarball には独自の Python（.install/bundled-python3-unix-darwin-*）が同梱されています。

ターミナルで必要な操作は、以下の 3 つのブロックを一度実行するだけです。

1. uv をインストールする

curl -LsSf https://astral.sh/uv/install.sh | sh
which uvx      # note this absolute path — Claude Desktop will need it

通常は /Users/<you>/.local/bin/uvx にあります。

2. Google Cloud CLI をインストールする

お使いのチップに合ったビルドを選んでください。uname -m を実行すると、Apple Silicon では arm64、Intel では x86_64 と表示されます。

# Apple Silicon
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz
tar -xzf google-cloud-cli-darwin-arm.tar.gz

# Intel — same, with the other file
# curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-x86_64.tar.gz
# tar -xzf google-cloud-cli-darwin-x86_64.tar.gz

./google-cloud-sdk/install.sh --quiet

brew install --cask google-cloud-sdk は避けてください。Homebrew 自体に Command Line Tools が必要です。このセクションで回避しようとしているのが、まさにそれです。

3. 認証する

./google-cloud-sdk/bin/gcloud auth application-default login
./google-cloud-sdk/bin/gcloud auth application-default set-quota-project your-gcp-project

これにより、Google のライブラリが直接読み取る認証情報ファイルが書き込まれます。以降、gcloud を PATH に含める必要はありません。 必要なのはここでの一度だけです。そのため、GUI から起動した Claude Desktop でも、シェルが見えなくても BigQuery にクエリを実行できます。

アカウントには、クエリの実行先プロジェクトで BigQuery Job User、読み取り対象の各データセットで BigQuery Data Viewer が必要です。多くの場合、これらは別々のプロジェクトです。

4. 動作を確認する

BQ_PROJECT=your-gcp-project uvx data-platform-mcp doctor

次に、クライアントに登録します。Claude Desktop または Claude Code。

代替方法：アナリストがターミナルをまったく使わない場合

それでも難しい場合は、管理者が認証情報に関する作業を一元的に行い、アナリストは uv だけをインストールできます。つまり、ステップ 2 とステップ 3 を丸ごと省略できます。（macOS 固有の方法ではなく、どの OS でも同じように動作します。）

# the admin, once, on their own machine
data-platform-mcp setup --project your-gcp-project --datasets sales,events
gcloud iam service-accounts keys create analyst-key.json \
  --iam-account [email protected]

アナリストはそのファイルを保存し、設定でそのファイルを指定します。

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["data-platform-mcp@latest"],
      "env": {
        "BQ_PROJECT": "your-gcp-project",
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/YOU/keys/analyst-key.json"
      }
    }
  }
}

このトレードオフは現実のものであり、明示する価値があります。 キーファイルはノートパソコンに保存される有効期間の長い認証情報ですが、gcloud auth application-default login では個人に紐づいた短期間のトークンが発行されます。setup --datasets で作成されたアカウントは指定したデータセットしか読み取れず、ノートパソコンを紛失した場合もキーを一元的に直ちに失効できるため、この方法には妥当性があります。しかし、明らかに安全性は劣ります。また、アナリストごとの秘密情報なので、共有設定ファイルやリポジトリには置かないでください。

---

Linux

Command Line Tools に相当する問題はなく、同じ 2 つをインストールします。

curl -LsSf https://astral.sh/uv/install.sh | sh
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
tar -xzf google-cloud-cli-linux-x86_64.tar.gz
./google-cloud-sdk/install.sh --quiet
./google-cloud-sdk/bin/gcloud auth application-default login

次に、動作を確認し、クライアントに登録します。

---

Windows

エンドツーエンドでは検証されていません。 以下のダウンロード URL とインストール先は確認済みですが、この手順自体は Windows マシンで実行していません。CI では Linux のみをテストしています。テスト済みの手順ではなく、慎重に導き出した手順として扱ってください。手順に誤りがあれば、issue を作成してください。

1. uv をインストールする

PowerShell で：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

これにより、uv.exe と uvx.exe が %USERPROFILE%\.local\bin にインストールされます。正確なパスを確認してください。デスクトップの設定で完全なパスが必要です：

(Get-Command uvx).Source

2. Google Cloud CLI をインストールする

GoogleCloudSDKInstaller.exe をダウンロードして実行します。 「Bundled Python」 にチェックを入れたままにしてください。これにより、macOS の tarball と同様、別途 Python をインストールしなくても SDK を実行できます。

3. 認証する

更新された PATH が反映されるよう、新しい PowerShell ウィンドウで次を実行します：

gcloud auth application-default login
gcloud auth application-default set-quota-project your-gcp-project

これにより、認証情報が %APPDATA%\gcloud\application_default_credentials.json に書き込まれます。Google のライブラリはこのファイルを直接読み取るため、その後 gcloud を PATH に含める必要はありません。

4. 動作を確認する

$env:BQ_PROJECT="your-gcp-project"; uvx data-platform-mcp doctor

5. Claude Desktop を設定する

%APPDATA%\Claude\claude_desktop_config.json — 存在しない場合は作成します。 JSON ではバックスラッシュを 2 つ重ねる必要があります。また、パスは絶対パスでなければなりません：

{
  "mcpServers": {
    "bigquery": {
      "command": "C:\\Users\\YOU\\.local\\bin\\uvx.exe",
      "args": ["data-platform-mcp@latest"],
      "env": {
        "BQ_PROJECT": "your-gcp-project"
      }
    }
  }
}

C:\Users\YOU\... を (Get-Command uvx).Source の出力に置き換え、各 \ を \\ として記述します。その後、Claude Desktop を完全に終了して再起動します。

失敗した場合、ログは %APPDATA%\Claude\logs\ にあります。そこに ENOENT と表示される場合、command のパスが間違っているか、バックスラッシュが 2 つに重ねられていません。macOS で発生するものと同じエラーですが、間違える方法が 1 つ増えています。

---

クイックスタート（ユーザーごと）

各ユーザーがそれぞれローカルコピーを実行します。クエリは各自の BigQuery/IAM 権限で実行されるため、既存のアクセス制御によって閲覧できる対象が決まります。

まず、お使いのプラットフォームの前提条件をインストールしてから、ここに戻ってください — macOS、Linux、Windows。

1. インストールする

このパッケージは data-platform-mcp として公開されています（bigquery-mcp は無関係なプロジェクトによって PyPI で既に使用されています）。チェックアウトは不要です。クライアントが直接取得して実行できます：

uvx data-platform-mcp --version

ソースから開発用にインストールする場合：

git clone [email protected]:deBilla/bigquery-mcp.git
cd bigquery-mcp

python3 -m venv .venv
./.venv/bin/pip install -e .

どちらの方法でも data-platform-mcp コマンドがインストールされます。クライアントはこのコマンドを実行します。

2. Google に認証する（初回のみ）

上記のプラットフォーム別セクションで説明しています。macOS の手順 3、または他のプラットフォームでは同等の gcloud auth application-default login を使用します。その後、クエリはアプリケーションのデフォルト認証情報を使って、ユーザー自身の認証情報で実行されます。

代わりにサービスアカウントキーを使う場合は？ GOOGLE_APPLICATION_CREDENTIALS にそのパスを設定します。ただし、シェルではなく、MCP サーバーの起動時に設定してください：

// in your client's MCP config, alongside BQ_PROJECT
"env": {
  "BQ_PROJECT": "your-gcp-project",
  "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/key.json"
}

クライアントは、設定で指定された環境変数だけを使ってサーバーをサブプロセスとして起動します。ターミナルでこの変数をエクスポートしてもサーバーには影響しません。これは認証情報がまったくない場合とは別のエラーですが、外部から見ると同じように見えます。

3. セットアップを確認する

BQ_PROJECT=your-gcp-project data-platform-mcp doctor

認証情報、ジョブの権限、データセットの可視性、そして見落とされやすいデータセットのリージョンを確認します。BigQuery は異なるロケーションにあるデータセットをクエリできません。また、BigQuery のエラーには、要求されたロケーションもデータセットのロケーションも示されないため、テーブルが存在しないように見えます。doctor は両方を表示します：

[  ok  ] run a query in my-project (location US)
[  ok  ] 39 datasets visible (no allowlist; all are readable)
[ warn ] 6 of 39 datasets are outside location US
         US-CENTRAL1: analytics_raw, business_data, ds_public, pg_public, public, recommendations
         BigQuery cannot query these from US, and cannot join them with
         datasets that are in it.
         Fix:  set BQ_LOCATION to the region you need, and run a separate
               server for datasets in another one.

別のリージョンにあるデータセットは警告になります。BQ_DATASET_ALLOWLIST に含まれるデータセットは、どのツール呼び出しでも読み取れないため、エラーになります。

4. AI クライアントに登録する

your-gcp-project を GCP プロジェクト ID に置き換えます。

Claude Code — 公開後：

claude mcp add bigquery \
  --env BQ_PROJECT=your-gcp-project \
  -- uvx data-platform-mcp

ソースからインストールする場合は、代わりにチェックアウト先を指定します（/abs/path/bigquery-mcp を置き換えてください）：

claude mcp add bigquery \
  --env BQ_PROJECT=your-gcp-project \
  -- /abs/path/bigquery-mcp/.venv/bin/data-platform-mcp

Claude Desktop — 専用セクションを参照してください。絶対パスが必要です。

5. クライアントを再起動して質問する

「利用可能なデータセットはどれですか？ sales データセットの orders テーブルには何行ありますか？」

---

Claude Desktop

データチームのほとんどのメンバーは CLI ではなく Desktop を使いますが、Desktop には CLI にはない失敗の原因が一つあります。

Claude Desktop はシェルの PATH を引き継ぎません。 Finder から起動するため、uvx、python、Homebrew や uv でインストールしたものは認識されません。"command": "uvx" と指定した設定は ENOENT で失敗します。サーバーは起動せず、エラーには原因ではなくコマンドが表示されます。このファイル内のパスはすべて絶対パスにする必要があります。

問題が起きないものは、認証情報です。Application Default Credentials は Google ライブラリが直接読み込むファイルなので、クエリを実行するために gcloud を PATH に追加する必要はありません。このファイルを作成するときに、ターミナルで一度だけ必要です。環境変数がまったくない状態でこのサーバーを実行し、クエリが成功することを確認しました。

1. インストールと認証

まずプラットフォームのセットアップを行います。macOS（2 回貼り付けるだけで、Xcode ツールは不要です）、Linux、または Windows を参照してください。必要なのは、セットアップで which uvx が出力した絶対パスと、gcloud auth application-default login の完了です。

2. 設定を編集する

Claude Desktop の Settings → Connectors にはホストされたコネクターが表示されます。このサーバーのようなローカルサーバーは、そこには追加しません。代わりに JSON ファイルに記述します。

Settings → Developer → Edit Config を開くと編集できます。または、直接編集してください。

OS	ファイル
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

通常、このファイルはすでに存在し、Desktop の設定が保存されています。 mcpServers をトップレベルのキーとして追加してください。ファイルを置き換えると、既存の設定が失われます。本当にファイルが存在しない場合は、以下のブロックだけを含めて作成してください。

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["data-platform-mcp@latest"],
      "env": {
        "BQ_PROJECT": "your-gcp-project"
      }
    }
  }
}

/Users/YOU/.local/bin/uvx を、which uvx が出力したパスに置き換えてください。Windows では C:\\Users\\YOU\\.local\\bin\\uvx.exe のようなパスになり、JSON ではバックスラッシュを二重にする必要があります。

すでに設定があるファイルに統合すると、次のようになります。mcpServers は既存の設定を置き換えるのではなく、その横に配置します。

{
  "preferences": { "...": "your existing settings, left alone" },
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["data-platform-mcp@latest"],
      "env": { "BQ_PROJECT": "your-gcp-project" }
    }
  }
}

再起動する前に、引き続き正しく解析できることを確認してください。余分なカンマがあると、すべてのサーバーが気付かないうちに無効になります。

python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

3. Claude Desktop を再起動する

完全に終了してから再度開いてください。ウィンドウの再読み込みだけでは不十分です。サーバーはメッセージボックスのツールアイコンの下に表示されます。

複数のウェアハウスを管理する

JSON が大きくなるのを避けるため、環境を ~/.config/data-platform-mcp/config.toml に記述してください（環境を参照）。Desktop の設定には env ブロックが不要になり、どのマシンでも同じ設定を使えます。

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOU/.local/bin/uvx",
      "args": ["data-platform-mcp@latest"]
    }
  }
}

チームで使うには、この方法がより適しています。共有する設定ファイルが 1 つになり、JSON にプロジェクト ID を記述せずに済みます。

動作しない場合

Desktop では原因がわかりにくいため、次の順に確認してください。

1. ターミナルで doctor を実行します。 認証情報、ロール、データセットの可視性、リージョンをまとめて報告します。セットアップの問題と Desktop の問題を見分ける最も手早い方法です。

   BQ_PROJECT=your-gcp-project /Users/YOU/.local/bin/uvx data-platform-mcp doctor
   

2. ログを確認します。 macOS の場合：~/Library/Logs/Claude/mcp*.log。ここに ENOENT または "command not found" がある場合は、command のパスが間違っています。which uvx に戻って確認してください。
3. JSON が正しく解析できるか確認します。 末尾のカンマがあると、すべてのサーバーが気付かないうちに無効になります。

   python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

安全性

• すべてのクエリは、検証とスキャンされるバイト数の見積もりのため、まずドライランされます。
• 実行されるのは SELECT / WITH 文のみです。書き込み、DDL、DML は実行されません。
• コストの確認： BQ_WARN_BYTES（デフォルトは 1 GB）を超えるスキャンが見積もられたクエリは実行されません。推定スキャンサイズと金額が status: "confirmation_required" とともに返されるため、クライアントは実行前に確認を求めることができます。実行するには、confirm_expensive=true を指定して再度呼び出してください。
• 上限： BQ_MAX_BYTES_BILLED（デフォルトは 5 GB）を超えるクエリは、確認を得ても実行されません。想定外のコストを防ぐための最終手段です。
• オプションのデータセット許可リストを使って、読み取り可能なデータセットを制限できます。
• 拒否はプロトコルエラーです。 サーバーが実行を拒否した場合（SELECT 以外の文、許可されていないデータセット、上限を超えるクエリなど）は、MCP の isError が設定されて返されるため、結果と誤認されることはありません。意図的な例外は confirmation_required です。これはエージェントがその内容を伝えてから再度実行するため、通常の結果として返されます。
• レスポンスのサイズには上限があります。 run_query は、シリアライズされたレスポンスが約 40k 文字に達すると行の追加を停止し、stopped_for_size を設定します。これにより、幅の広い結果がコンテキストウィンドウを気付かないうちに使い切ることはありません。部分的な回答には、必ずその旨が示されます。
• SQL が監査ログに記録されることはありません。 記録されるのはハッシュと長さのみです。クエリテキストには、フィルター対象のユーザー ID やメールアドレスが含まれることがよくあります。

コスト確認の流れ

run_query(sql)
   │  dry run estimates the scan
   ├── ≤ 1 GB ........... runs, returns rows + estimated_cost_usd
   ├── 1–5 GB .......... status: confirmation_required (size + $ estimate) → ask user
   │                      → run_query(sql, confirm_expensive=true) runs it
   └── > 5 GB ........... rejected, never runs

---

設定（環境変数）

変数	デフォルト	意味
BQ_MCP_ENVIRONMENTS	(none)	環境名と設定の JSON マップです。設定ファイルより優先されます。
BQ_MCP_DEFAULT_ENVIRONMENT	(safest, else first)	呼び出しで environment が省略された場合に使用する環境です。未設定の場合は、ステージング／開発環境が優先されます。
BQ_MCP_CONFIG	~/.config/data-platform-mcp/config.toml	TOML 設定ファイルのパス
BQ_IMPERSONATE_SERVICE_ACCOUNT	(none)	偽装する読み取り専用サービスアカウント
BQ_PROJECT	(ADC project)	クエリ対象の BigQuery データセットがある GCP プロジェクト ID です。認証情報に関連付けられたプロジェクトにフォールバックします。どちらも設定されていない場合、ツールは手順を示すエラーを返します。
BQ_LOCATION	US	BigQuery のロケーション
BQ_WARN_BYTES	1073741824 (1 GB)	この値を超える場合、実行前にユーザーへ確認を求めます
BQ_MAX_BYTES_BILLED	5368709120 (5 GB)	クエリごとのスキャン上限。超過することはありません
BQ_COST_PER_TIB_USD	6.25	コスト見積もりの表示に使うオンデマンド料金
BQ_ROW_LIMIT	200	返される行のデフォルト数
BQ_DATASET_ALLOWLIST	(empty = all)	カンマ区切りのデータセット ID
BQ_MCP_TRANSPORT	stdio	stdio（サブプロセス）または http／sse（ネットワーク経由で提供）
BQ_MCP_HOST	127.0.0.1	トランスポートが http／sse の場合のバインド先ホストです。run-http.sh は、コンテナから接続できるようにこれを 0.0.0.0 に上書きします。以下のセキュリティに関する注意事項を参照してください。
BQ_MCP_PORT	8765	トランスポートが http／sse の場合のバインド先ポート
BQ_MCP_AUDIT_LOG	~/.local/state/data-platform-mcp/audit.jsonl	すべてのツール呼び出しを記録する JSONL ファイルです。off にすると無効になります。SQL テキストは記録されず、ハッシュと長さのみが記録されます。
BQ_MCP_LOG_LEVEL	INFO	stderr ログの詳細度

デフォルトではサーバーは stdio で通信します。クライアント（Claude Code、Claude Desktop）がサーバーを起動する場合に適しており、上記のクイックスタートでも使用されます。

---

上級編：HTTP 経由で提供する

各クライアントがそれぞれサーバーを起動するのではなく、リモートまたはコンテナ化されたクライアントからサーバーにアクセスするには、HTTP 経由で実行します。

BQ_PROJECT=your-gcp-project ./run-http.sh
# Serving … on http://0.0.0.0:8765/mcp

クライアントは URL で接続します（Claude Code）：

claude mcp add --transport http bigquery http://<host>:8765/mcp

⚠️ セキュリティ： HTTP エンドポイントには認証がなく、すべてのクエリは接続しているユーザーの認証情報ではなく、ホストの ADC 認証情報で実行されます。ポートにアクセスできる人は誰でも、あなたの ID で BQ_PROJECT への完全な読み取りアクセスが可能です。信頼できるネットワークでのみ公開してください（BQ_MCP_HOST=127.0.0.1 にバインドし、SSH トンネル／VPN、または認証プロキシを使用します）。このモードを想定したコンテナ化クライアントの設定については、docs/nanoclaw.md を参照してください。

サーバーをデプロイする場合は、個人用 ADC を使用せず、BigQuery Data Viewer と Job User のロールを持つサービスアカウントキーを GOOGLE_APPLICATION_CREDENTIALS で指定してください。

---

開発

コントリビューションを歓迎します。詳しくは CONTRIBUTING.md と、最初に取り組む課題を探すための good first issue ラベルをご覧ください。

./.venv/bin/pip install -e ".[dev]"
./.venv/bin/python -m pytest

テストスイートに認証情報やネットワークは不要です。すべてのテストは tests/conftest.py のフェイクを対象に実行されるため、決定論的で無料です。各レイヤーの内容：

ファイル	対象
test_protocol.py	実際のメモリー内クライアントセッションを通じた MCP コントラクト：ツールセット、読み取り専用アノテーション、生成されたスキーマ、拒否時の isError
test_query_guard.py	コストゲート：実行されるもの、拒否されるもの、ユーザーに返されるもの、制限について呼び出し元に伝えられる内容
test_payload_shape.py	パーティション分割の落とし穴やネストされたフィールドのフラット化を含む、フェイクテーブルに対するレスポンスの形状
test_observability.py	監査証跡と、SQL テキストが監査証跡に記録されないことの保証
test_diagnostics.py	doctor のレポート。早期検出を目的とするリージョンと許可リストのエラーを含む
test_environments.py	環境間のルーティング、環境ごとの制限、なりすまし対象の指定
test_config.py	環境レジストリ、エイリアス、TOML ファイル、以前はインポート時のクラッシュを引き起こしていたプロジェクト未指定エラー
test_errors.py	認証エラーに、それを修正するコマンドが含まれること
test_formatting.py	ユーザーに承認を求めるサイズとコストの数値
test_eval_scoring.py	各ケースが拒否するために設計された軌跡を入力とする、評価スコアラー

評価

さらに 2 つのレイヤーは有効な認証情報を必要とするため、pytest の対象外です。 evals/measure.py は、各ツールからクライアントが実際に受け取る内容を記録し、evals/tool_use_evals.py は claude CLI を通じて実際の質問を行い、サーバー自身の監査ログから軌跡を評価します。つまり、どのツールが、どの環境に対して、どの引数で実行されたかを評価します。

./.venv/bin/python evals/measure.py                     # payload sizes
./.venv/bin/python evals/tool_use_evals.py              # 6 cases, spends tokens
./.venv/bin/python evals/tool_use_evals.py --rescore    # re-score saved replies, free

各ケースで検出される内容については evals/README.md を、前回の実行で測定された内容については evals/BASELINE.md を参照してください。このサーバーで最も効果的に変更できるのはツールとサーバーの説明であり、それらを変更する必要があるかどうかを教えてくれるのは評価だけです。

ミューテーションテスト

最初の実行でテストスイートが通っても何も証明されないため、上記の保証が成り立つかどうかを、意図的に壊して検証しました。拒否をエラー形式の戻り値に戻す、生の SQL をログに記録する、列名からパーティション分割を推測する、レスポンスの予算を削除する、監査ラッパーから functools.wraps を削除する、確認によってハード上限を回避させる、古いテーブルの検出を無効にする、許可リストのチェックを削除する、といった変更です。どの変更でもテストスイートは失敗します。

アップグレード

uvx は初回の実行時にのみ最新バージョンを解決し、その後はキャッシュされた環境を無期限に再利用します。["data-platform-mcp"] のままのサーバーは、最初にダウンロードしたビルドを実行し続けます。後のリリースで追加されたツールは単に表示されず、「アップグレードがまだ反映されていない」のではなく、「このサーバーにはその機能がない」と受け取られてしまいます。起動のたびに再解決されるよう、@latest を指定してください。

"args": ["data-platform-mcp@latest"]

その後、クライアントを完全に終了してから再度開いてください。MCP サーバーはクライアントの起動時に起動されるため、再読み込みしても古いプロセスが実行されたままになります。

設定を編集せずに一度だけアップグレードするには、uv cache clean data-platform-mcp を実行します（uv tool install でインストールした場合は uv tool upgrade data-platform-mcp を実行します）。list_environments は server_version を報告するため、会話中に実際に実行されているバージョンを確認できます。

リリース

バージョン番号は2つのファイルに記載されており、値が一致しないタグは CI で拒否されます。不一致があると、パッケージが示すコードとは異なるコードを指すタグが公開されてしまうためです。（__version__ はインストール済みの配布物から読み取られるため、食い違うことはありません。）

# 1. bump both to the same value
#      pyproject.toml   project.version
#      server.json      version  AND  packages[0].version

# 2. tag and push
git tag v0.3.3 && git push origin v0.3.3

このタグによって .github/workflows/release.yml が起動され、バージョンの一致を確認し、ビルドを行い、Trusted Publishing を介して PyPI に公開した後、リリースを MCP registry に登録します。どちらの手順でもトークンは保存しません。PyPI はこのリポジトリと pypi 環境からの OIDC を使用し、レジストリは GitHub OIDC を使用します。初回リリース前に、どちらも一度だけ設定する必要があります。

• PyPI： deBilla/bigquery-mcp リポジトリ、release.yml ワークフロー、pypi 環境を指定して、https://pypi.org/manage/account/publishing/ で信頼されたパブリッシャーを追加します。
• GitHub： リポジトリの設定で pypi 環境を作成します。

CI のチェック項目

.github/workflows/ci.yml は、すべてのプッシュとプルリクエストで実行されます。

ジョブ	チェック項目
test	Python 3.11、3.12、3.13 でテストスイートを実行します。ランナーに GCP の認証情報がない状態で実行することが重要です。
safety	管理対象ファイルに認証情報らしい文字列がないこと、.env／.mcp.json が未追跡であること、src/ 内のどこにも BigQuery クライアントの変更系呼び出しがないことを確認します。
package	ビルドし、twine check を実行して、ローカル設定が sdist に混入していないことを検証します。その後、クリーンな venv に wheel をインストールして実際のプロトコルを実行し、5つのツールすべてに読み取り専用の注釈とドキュメントがあり、指示が保持されていることを確認します。

最後のチェックが重要です。正常にインストールできても最初のリクエストで停止するパッケージを検出します。この種の障害は、ユニットテストでは検出できません。

ライセンス

MIT — LICENSE を参照してください。