BigQuery MCP サーバー

Google BigQuery にアクセスするためのモデルコンテキストプロトコル（MCP）サーバー。このサーバーにより、大規模言語モデル（LLM）は BigQuery データセットの構造を理解し、SQL クエリを実行できるようになります。

特徴

認証と接続管理

アプリケーションデフォルト認証情報（ADC）またはサービスアカウントキーファイルをサポート
構成可能なプロジェクトIDと場所の設定
起動時の認証検証

ツール

クエリ
- 読み取り専用（SELECT）BigQuery SQL クエリを実行する
- 設定可能な最大結果と課金バイト数
- SELECT以外のクエリを防ぐためのセキュリティチェック
すべてのデータセットの一覧
- プロジェクト内のすべてのデータセットを一覧表示する
- データセットIDの配列を返します
データセットを含むすべてのテーブルの一覧
- 特定のデータセット内のすべてのテーブルとそのスキーマを一覧表示する
- データセットIDパラメータが必要です
- テーブルID、スキーマ、時間パーティション情報、および説明を返します
テーブル情報を取得する
- テーブルスキーマとサンプルデータ (最大 20 行) を取得します。
- パーティションフィルターを使用したパーティションテーブルのサポート
- フィルターのないパーティションテーブルに対するクエリの警告
ドライランクエリ
- クエリの有効性をチェックし、実行せずにコストを見積もる
- 処理サイズと推定コストを返します

セキュリティ機能

SELECTクエリのみ許可されます（読み取り専用アクセス）
過剰なコストを防ぐために、クエリ処理のデフォルトの制限は 500 GB です。
パーティションテーブルに対するパーティションフィルタの推奨事項
認証資格情報の安全な取り扱い

インストール

ローカルインストール

# Clone the repository
git clone https://github.com/yourusername/bigquery-mcp-server.git
cd bigquery-mcp-server

# Install dependencies
bun install

# Build the server
bun run build

# Install command to your own path.
cp dist/bigquery-mcp-server /path/to/your_place

Dockerのインストール

Docker コンテナ内でサーバーを実行することもできます。

# Build the Docker image
docker build -t bigquery-mcp-server .

# Run the container
docker run -it --rm \
  bigquery-mcp-server \
  --project-id=your-project-id

または Docker Compose を使用します:

# Edit docker-compose.yml to set your project ID and other options
# Then run:
docker-compose up

MCP構成

このサーバーを MCP 対応 LLM で使用するには、MCP 構成に追加します。

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",
        "your-project-id",
        "--location",
        "asia-northeast1",
        "--max-results",
        "1000",
        "--max-bytes-billed",
        "500000000000"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
      }
    }
  }
}

サービスアカウントキーファイルの代わりにアプリケーションのデフォルト認証情報を使用することもできます。

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",
        "your-project-id",
        "--location",
        "asia-northeast1",
        "--max-results",
        "1000",
        "--max-bytes-billed",
        "500000000000"
      ]
    }
  }
}

アプリケーションのデフォルト資格情報の設定

アプリケーションのデフォルト資格情報を使用して認証するには:

Google Cloud SDK をまだインストールしていない場合はインストールします。
# For macOS brew install --cask google-cloud-sdk # For other platforms, see: https://cloud.google.com/sdk/docs/install
認証コマンドを実行します。
gcloud auth application-default login
指示に従って、BigQuery プロジェクトにアクセスできる Google アカウントでログインします。
認証情報はローカルマシンに保存され、BigQuery MCP サーバーによって自動的に使用されます。

テスト

テストとデバッグにはインスペクターを使用できます。

npx @modelcontextprotocol/inspector dist/bigquery-mcp-server --project-id={{your_own_project}}

使用法

ヘルパースクリプトの使用

付属のrun-server.shスクリプトを使用すると、一般的な構成でサーバーを簡単に起動できます。

# Make the script executable
chmod +x run-server.sh

# Run with Application Default Credentials
./run-server.sh --project-id=your-project-id

# Run with a service account key file
./run-server.sh \
  --project-id=your-project-id \
  --location=asia-northeast1 \
  --key-file=/path/to/service-account-key.json \
  --max-results=1000 \
  --max-bytes-billed=500000000000

手動実行

コンパイルされたバイナリを直接実行することもできます。

# Run with Application Default Credentials
./dist/bigquery-mcp-server --project-id=your-project-id

# Run with a service account key file
./dist/bigquery-mcp-server \
  --project-id=your-project-id \
  --location=asia-northeast1 \
  --key-file=/path/to/service-account-key.json \
  --max-results=1000 \
  --max-bytes-billed=500000000000

クライアントの例

サンプルの Node.js クライアントは、 examplesディレクトリに含まれています。

# Make the example executable
chmod +x examples/sample-query.js

# Edit the example to set your project ID
# Then run it
cd examples
./sample-query.js

コマンドラインオプション

--project-id : Google Cloud プロジェクト ID (必須)
--location : BigQuery の場所 (デフォルト: asia-northeast1)
--key-file : サービスアカウントキーファイルへのパス (オプション)
--max-results : 返される最大行数（デフォルト: 1000）
--max-bytes-billed : 処理する最大バイト数 (デフォルト: 5000000000000、500GB)

必要な権限

サービスアカウントまたはユーザー資格情報には、次のいずれかが必要です。

roles/bigquery.user (推奨)

あるいは、これら両方:

roles/bigquery.dataViewer (テーブルデータの読み取り用)
roles/bigquery.jobUser (クエリ実行用)

使用例

クエリツール

{
  "query": "SELECT * FROM `project.dataset.table` LIMIT 10",
  "maxResults": 100
}

すべてのデータセットの一覧表示ツール

// No parameters required

データセットツールですべてのテーブルを一覧表示する

{
  "datasetId": "your_dataset"
}

テーブル情報取得ツール

{
  "datasetId": "your_dataset",
  "tableId": "your_table",
  "partition": "20250101"
}

ドライランクエリツール

{
  "query": "SELECT * FROM `project.dataset.table` WHERE date = '2025-01-01'"
}

エラー処理

サーバーは、次の詳細なエラーメッセージを提供します。

認証失敗
権限の問題
無効なクエリ
パーティションフィルターがありません
過剰なデータ処理要求

コード構造

サーバーは次の構造で構成されます。

src/
├── index.ts              # Entry point
├── server.ts             # BigQueryMcpServer class
├── types.ts              # Type definitions
├── tools/                # Tool implementations
│   ├── query.ts          # query tool
│   ├── list-datasets.ts  # list_all_datasets tool
│   ├── list-tables.ts    # list_all_tables_with_dataset tool
│   ├── table-info.ts     # get_table_information tool
│   └── dry-run.ts        # dry_run_query tool
└── utils/                # Utility functions
    ├── args-parser.ts    # Command line argument parser
    └── query-utils.ts    # Query validation and response formatting

ライセンス

マサチューセッツ工科大学

BigQuery MCP Server

Integrations