Claude Desktop × BigQuery をWSLで連携する方法

この記事では、Claude DesktopとBigQueryを連携するために必要な手順を、WSL環境を想定してまとめます。
「MCPサーバー」という仕組みを使うと、Claude DesktopからBigQueryのデータセットやテーブルを簡単に参照できるようになります。

<iframe width="560" height="315" 
        src="https://www.youtube.com/embed/U-EP0rwJGd8" 
        frameborder="0" 
        allowfullscreen>
</iframe>

目次

1. 概要


2. 準備

1. WSLにNode.js / npm / npxをインストール


2. GCPプロジェクト＆BigQuery API有効化


3. 認証方法を決める（ADC or サービスアカウントキー）




3. 実際の設定

1. シンプルなローカルテスト（ターミナル）


2. Claude Desktopの設定ファイルを編集




4. 動作確認


5. よくあるトラブルシューティング


6. まとめ




---

# 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をインストール

1. 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


2. バージョン確認:

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有効化

1. GCPコンソールで新規プロジェクトを作成するか、既存プロジェクトを使う。


2. BigQuery API を有効にする。


3. 必要に応じて「BigQuery→データセット作成」でテーブルを用意する。



## 2.3. 認証方法を決める

アプリケーションデフォルト認証 (ADC)

1. gcloud auth application-default login


2. gcloud config set project <PROJECT_ID>
これだけで、ローカル環境のADC認証が済みます。



サービスアカウントキー (JSON)

1. 「IAMと管理」→「サービスアカウント」で新規作成


2. ロール: bigquery.dataEditor, bigquery.jobUser 等を付与


3. 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. 動作確認

1. Claude Desktop を再起動。


2. BigQuery MCPサーバーが起動していれば、ログに「Server started and connected successfully」などが出力されます。


3. Claudeに「BigQueryでテーブルをSELECTして」と頼むか、「resources/list」でデータセットやテーブル一覧を見られるはず。


4. テーブルがない場合は「Found 0 tables」となるため、BigQueryコンソールなどでテーブルを作っておきましょう。




---

# 5. よくあるトラブルシューティング

1. npx: command not found

bash -i か、source ~/.nvm/nvm.sh を使ってNVMを初期化してください。



2. Invalid project ID '--project-id=xxx'

スペース区切り vs イコール区切りの問題。

--project-id my-project のようにスペースで区切るか、--project-id=my-project など書き方を調整してください。



3. 「テーブルが0件」

本当にテーブルが無いか、読み取り専用サーバーでCREATE TABLEできない。

事前にBigQueryコンソールでテーブルを用意しましょう。



4. 「permission denied」

サービスアカウントに bigquery.dataEditor / bigquery.jobUser を付与していない。

gcloud projects add-iam-policy-binding <PROJECT_ID> --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文を実行して」と頼めば結果を返してくれるはずです。お疲れさまでした！