BigQuery MCP Server

BigQuery MCP サーバー

Google BigQuery にアクセスするための Model Context Protocol（MCP）サーバーです。このサーバーを使うと、大規模言語モデル（LLM）が BigQuery のデータセット構造を把握し、SQL クエリを実行できます。

機能

認証と接続管理

• Application Default Credentials（ADC）またはサービスアカウントのキーファイルに対応
• プロジェクト ID とロケーションの設定が可能
• 起動時に認証を検証

ツール

1. query

   • 読み取り専用（SELECT）の BigQuery SQL クエリを実行
   • 最大結果数と課金対象の最大バイト数を設定可能
   • SELECT 以外のクエリを防ぐためのセキュリティチェック

2. list_all_datasets

   • プロジェクト内のすべてのデータセットを一覧表示
   • データセット ID の配列を返す

3. list_all_tables_with_dataset

   • 指定したデータセット内のすべてのテーブルとそのスキーマを一覧表示
   • datasetId パラメーターが必要
   • テーブル ID、スキーマ、時間パーティション情報、説明を返す

4. get_table_information

   • テーブルのスキーマとサンプルデータ（最大 20 行）を取得
   • パーティションフィルターを使用したパーティション分割テーブルに対応
   • フィルターを指定せずにパーティション分割テーブルをクエリした場合に警告

5. dry_run_query

   • クエリを実行せずに有効性を確認し、コストを見積もり
   • 処理データ量と推定コストを返す

セキュリティ機能

• SELECT クエリのみ許可（読み取り専用アクセス）
• 過剰なコストを防ぐため、クエリ処理量の上限をデフォルトで 500GB に設定
• パーティション分割テーブルに対するパーティションフィルターの使用を推奨
• 認証情報を安全に取り扱い

インストール

ローカルインストール

# 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"
      }
    }
  }
}

サービスアカウントのキーファイルの代わりに、Application Default Credentials を使用することもできます。

{
  "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"
      ]
    }
  }
}

Application Default Credentials の設定

Application Default Credentials を使って認証するには、次の手順に従います。

1. まだインストールしていない場合は、Google Cloud SDK をインストールします。

   # For macOS
   brew install --cask google-cloud-sdk
   
   # For other platforms, see: https://cloud.google.com/sdk/docs/install
   

2. 認証コマンドを実行します。

   gcloud auth application-default login
   

3. BigQuery プロジェクトへのアクセス権を持つ Google アカウントでログインするための指示に従います。

4. 認証情報はローカルマシンに保存され、BigQuery MCP サーバーによって自動的に使用されます。

テスト

テストとデバッグには inspector を使用できます。

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：処理する最大バイト数（デフォルト：500000000000、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

ライセンス

MIT