この記事では、Claude DesktopとBigQueryを連携するために必要な手順を、WSL環境を想定してまとめます。
「MCPサーバー」という仕組みを使うと、Claude DesktopからBigQueryのデータセットやテーブルを簡単に参照できるようになります。
目次
-
概要
-
準備
-
WSLにNode.js / npm / npxをインストール
-
GCPプロジェクト＆BigQuery API有効化
-
認証方法を決める（ADC or サービスアカウントキー）
-
実際の設定
-
シンプルなローカルテスト（ターミナル）
-
Claude Desktopの設定ファイルを編集
-
動作確認
-
よくあるトラブルシューティング
-
まとめ
1. 概要
Claude Desktop: OpenAI ChatGPTのように、LLMとやり取りするGUIツール。
MCPサーバー: Claude Desktopに外部サービス（GitHub, Google Drive, BigQueryなど）を連携するための仕組み。
BigQuery MCPサーバー: @ergut/mcp-bigquery-server というnpmパッケージを使い、BigQueryと連携できる。
通常はWindows環境でNode.jsがインストールされていればそのまま動きますが、「WSLにしかNodeがない」ケースでも少し設定を変えれば連携可能です。
2. 準備
2.1. WSLにNode.js / npm / npxをインストール
- NVM (Node Version Manager) を使う場合:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
source ~/.nvm/nvm.sh
nvm install --lts
- バージョン確認:
node -v
npm -v
npx -v
これでNode.js / npm / npxが使える状態になればOK。
注意: WSLでNode.jsを使う場合、非対話型シェルだと.bashrcが読み込まれず、npxが見つからないことがあります。その際は bash -i で起動したり、source ~/.nvm/nvm.sh を明示的に呼び出す方法をとります。
2.2. GCPプロジェクト＆BigQuery API有効化
-
GCPコンソールで新規プロジェクトを作成するか、既存プロジェクトを使う。
-
BigQuery API を有効にする。
-
必要に応じて「BigQuery→データセット作成」でテーブルを用意する。
2.3. 認証方法を決める
アプリケーションデフォルト認証 (ADC)
-
gcloud auth application-default login
-
gcloud config set project
これだけで、ローカル環境のADC認証が済みます。
サービスアカウントキー (JSON)
-
「IAMと管理」→「サービスアカウント」で新規作成
-
ロール: bigquery.dataEditor, bigquery.jobUser 等を付与
-
JSONキーをダウンロードし、--key-file /path/to/key.json で指定
3. 実際の設定
3.1. シンプルなローカルテスト（ターミナル）
3.1.1. ADC利用の場合
npx -y @ergut/mcp-bigquery-server --project-id my-bigquery-project-xxxxxx --location xxxxxxxx
もし npx が見つからないなら:
source ~/.nvm/nvm.sh
npx -y @ergut/mcp-bigquery-server --project-id my-bigquery-project-xxxxx --location xxxxxxxxxx
正常に接続できると、ログに Initializing BigQuery with project ID: my-bigquery-project-xxxxxxxx and location: xxxxxxxx などが出力されます。
3.1.2. サービスアカウントキー利用の場合
npx -y @ergut/mcp-bigquery-server
--project-id my-bigquery-project-xxxxxxxxx
--location xxxxxxxx
--key-file /root/xxxxxxxx.json
上記JSONに書かれた client_email に対応するサービスアカウントのロールが足りないとエラーになります。
権限エラーが出たら gcloud projects add-iam-policy-binding などで bigquery.dataEditor を付与しましょう。
3.2. Claude Desktopの設定ファイルを編集
claude_desktop_config.json にBigQuery MCPサーバーを追記します。
WindowsでGUIを動かし、Node.jsがWSL内にしかない場合は以下のように設定:
{
"mcpServers": {
"bigquery": {
"command": "wsl",
"args": [
"bash",
"-i",
"-c",
// WSL内で npx 実行
"npx -y @ergut/mcp-bigquery-server my-bigquery-project-xxxxxxxx xxxxxxxx"
]
}
}
}
"command": "wsl" でWindowsからWSLを呼び出す
"-i" は対話型シェルで.bashrcが読み込まれ、nvm経由のNode.jsが使えるようにする
"npx -y @ergut/mcp-bigquery-server my-bigquery-project-xxxxxxxx xxxxxxxx" は、ポジショナル引数を使った例です（第1引数がProject ID、第2引数がLocation）。
サービスアカウントキーを使いたい場合は、さらに --key-file /root/xxxxxxxx.json を追加してください。
"npx -y @ergut/mcp-bigquery-server my-bigquery-project-xxxxxxxx xxxxxxxx --key-file /root/xxxxxxxx.json"
4. 動作確認
-
Claude Desktop を再起動。
-
BigQuery MCPサーバーが起動していれば、ログに「Server started and connected successfully」などが出力されます。
-
Claudeに「BigQueryでテーブルをSELECTして」と頼むか、「resources/list」でデータセットやテーブル一覧を見られるはず。
-
テーブルがない場合は「Found 0 tables」となるため、BigQueryコンソールなどでテーブルを作っておきましょう。
5. よくあるトラブルシューティング
- npx: command not found
bash -i か、source ~/.nvm/nvm.sh を使ってNVMを初期化してください。
- Invalid project ID '--project-id=xxx'
スペース区切り vs イコール区切りの問題。
--project-id my-project のようにスペースで区切るか、--project-id=my-project など書き方を調整してください。
- 「テーブルが0件」
本当にテーブルが無いか、読み取り専用サーバーでCREATE TABLEできない。
事前にBigQueryコンソールでテーブルを用意しましょう。
- 「permission denied」
サービスアカウントに bigquery.dataEditor / bigquery.jobUser を付与していない。
gcloud projects add-iam-policy-binding --member=serviceAccount:xxxx --role=roles/bigquery.dataEditor などで付与。
6. まとめ
WSLでNode.jsを使い、WindowsのClaude DesktopからBigQuery MCPサーバーを呼び出すときは、
claude_desktop_config.json の "command" を "wsl" にし、
bash -i -c "npx ..." の形で実行コマンドを1行にまとめるのがポイント。
BigQuery MCPサーバーが読み取り専用の場合、テーブルは事前に手動作成が必要です。
認証はADCかサービスアカウントキーか、お好みで選んでOK。
これでClaude Desktop × BigQuery連携がスムーズにできるようになります。
あとは実際にテーブルを用意して、Claudeに「SELECT文を実行して」と頼めば結果を返してくれるはずです。お疲れさまでした！