Bigquery Mcp

🗂️ BigQuery MCP サーバー

LLM が BigQuery のデータセットやテーブルを参照するための実用的な MCP サーバーです。多数のデータセットやテーブルを持つ大規模なプロジェクト向けに設計されており、高速かつ安全性を保ちながら、LLM のコンテキストを小さく抑えるよう最適化されています。

• デフォルトでは最小限：データセット名とテーブル名を一覧表示し、詳細は要求された場合にのみ取得します
• 大規模なプロジェクトを参照：名前で絞り込み、必要に応じて詳細なメタデータやスキーマを取得します
• テーブルをすばやく把握：任意のスキーマ、列の説明、充足率を使って、エージェントが関連性をすばやく判断できます
• 安全に実行：ガードレール（SELECT/WITH のみ、コメントの除去）を備えた読み取り専用のクエリ実行です
• ベクトル検索に対応：BigQuery をベクトルストアとして使用できます。詳しい設定手順については、ベクトル検索のセクションをご覧ください。

クイックスタート

前提条件： Python 3.10 以降と uv パッケージマネージャー

🚀 クイックセットアップ

オプション 1：PyPI から直接インストール（推奨）

# 1. Authenticate
gcloud auth application-default login

# 2. Run server
uvx bigquery-mcp --project YOUR_PROJECT --location US

オプション 2：ローカルにクローン（開発環境のセットアップ）

# 1. Clone and setup
git clone https://github.com/pvoo/bigquery-mcp.git
cd bigquery-mcp

# 2. Configure environment
cp .env.example .env
# Edit .env with your project and location

# 3. Run or inspect
make run      # Start server
make inspect  # Open MCP inspector

🔧 MCP クライアントの設定

オプション 1：PyPI パッケージ（推奨） 公開されている PyPI パッケージを使う、最も簡単なセットアップです：

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "bigquery-mcp",
        "--project", "your-project-id",
        "--location", "US"
     ]
    }
  }
}

オプション 2：ローカルにクローン（開発用）

# Clone first
git clone https://github.com/pvoo/bigquery-mcp.git

{
  "mcpServers": {
    "bigquery": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/bigquery-mcp", "run", "bigquery-mcp"],
      "env": {
        "GCP_PROJECT_ID": "your-project-id",
        "BIGQUERY_LOCATION": "US"
      }
    }
  }
}

🧪 セットアップのテスト

# Test with MCP inspector
npx @modelcontextprotocol/inspector uvx bigquery-mcp --project YOUR_PROJECT --location US

🔧 設定オプション

すべての設定は CLI 引数または環境変数で指定できます。CLI 引数が優先されます。

必須パラメーター

--project YOUR_PROJECT    # Google Cloud project ID
--location US             # BigQuery location (US, EU, etc.)

任意のパラメーター

# Dataset Access Control
--datasets dataset1 dataset2    # Restrict to specific datasets (default: all datasets)

# Query & Result Limits
--list-max-results 500          # Max results for basic list operations (default: 500)
--detailed-list-max 25          # Max results for detailed list operations (default: 25)
--max-bytes-billed 109951162777  # Max bytes billed per query job (~USD 0.50/query)

# Table Analysis
--sample-rows 3                 # Sample data rows returned in get_table (default: 3)
--stats-sample-size 500         # Rows sampled for column fill rate calculations (default: 500)

# Authentication
--key-file /path/to/key.json    # Service account key file (default: ADC)

環境変数

すべての CLI オプションに対応する環境変数があります：

export GCP_PROJECT_ID=your-project
export BIGQUERY_LOCATION=US
export BIGQUERY_ALLOWED_DATASETS=dataset1,dataset2
export BIGQUERY_LIST_MAX_RESULTS=500
export BIGQUERY_LIST_MAX_RESULTS_DETAILED=25
export BIGQUERY_MAX_BYTES_BILLED=109951162777
export BIGQUERY_SAMPLE_ROWS=3
export BIGQUERY_SAMPLE_ROWS_FOR_STATS=500
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

ベクトル検索の設定

詳しい設定手順については、ベクトル検索のセクションをご覧ください。

--embedding-model project.dataset.model
--embedding-tables dataset.table1 dataset.table2
--distance-type COSINE

🛠️ ツールの概要

この MCP サーバーは、LLM の効率を高めるよう最適化された 5 つの BigQuery ツールを提供します。

📊 スマートなデータセットとテーブルの検出

• list_datasets - 2 つのモードに対応：基本（名前のみ）と詳細（完全なメタデータ）
• list_tables - コンテキストに応じたテーブルの参照と、任意のスキーマ詳細の表示
• get_table - スキーマとサンプルデータを含む、テーブルの包括的な分析

🔍 安全なクエリ実行

• run_query - SELECT/WITH クエリのみを実行します。コスト追跡、安全性検証に対応し、クエリごとのデフォルトの課金上限は約 0.50 米ドルです。結果のサイズを制御するには、クエリで LIMIT 句を使用してください。

🔮 ベクトル検索（任意）

• vector_search - 2 つのモードを備えたツールです。埋め込みテーブルの検出（query_text なし）または意味的類似性検索の実行（query_text あり）を行います。

主な機能：

• ✅ デフォルトでは最小限 - 基本モードではトークン数を 70% 削減します
• ✅ 安全なクエリのみ - すべての書き込み操作をブロックします
• ✅ LLM 向けに最適化 - AI による分析に最適な構造化データを返します
• ✅ コストが明確 - 各クエリで処理されたバイト数を表示します
• ✅ デフォルトでコストを制限 - 設定を変更しない限り、各クエリジョブの上限を約 0.50 米ドルに設定します

🔮 ベクトル検索（任意）

BigQuery のベクトル埋め込みを使った意味的類似性検索を有効にします。

前提条件：BigQuery での埋め込みの設定

ベクトル検索を使用するには、埋め込みモデルと埋め込みを含むテーブルが必要です。

ステップ 1：Vertex AI 接続を作成する（初回のみ）

-- In BigQuery console or bq command line
-- This creates a connection to Vertex AI for generating embeddings
CREATE EXTERNAL CONNECTION `your-project.your-region.vertex-ai`
  OPTIONS (
    endpoint = 'https://your-region-aiplatform.googleapis.com',
    type = 'CLOUD_RESOURCE'
  );

ステップ 2：埋め込みモデルを作成する

CREATE OR REPLACE MODEL `your-project.your_dataset.text_embedding_model`
REMOTE WITH CONNECTION `your-project.your-region.vertex-ai`
OPTIONS (ENDPOINT = 'text-embedding-005');

ステップ 3：テーブルに埋め込みを追加する

-- Add embedding column to existing table
ALTER TABLE `your-project.your_dataset.products`
ADD COLUMN IF NOT EXISTS embedding ARRAY<FLOAT64>;

-- Generate embeddings for your text data
UPDATE `your-project.your_dataset.products` t
SET embedding = (
  SELECT ml_generate_embedding_result
  FROM ML.GENERATE_EMBEDDING(
    MODEL `your-project.your_dataset.text_embedding_model`,
    (SELECT t.name AS content),
    STRUCT(TRUE AS flatten_json_output)
  )
)
WHERE embedding IS NULL;

詳しい設定手順と接続の権限については、BigQuery のテキスト埋め込みに関するドキュメントをご覧ください。

ベクトル検索の MCP 設定

埋め込みを設定したら、MCP サーバーを設定します。

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "bigquery-mcp",
        "--project", "your-project",
        "--location", "US",
        "--embedding-model", "your-project.your_dataset.text_embedding_model",
        "--embedding-tables", "your_dataset.products", "your_dataset.documents"
      ]
    }
  }
}

設定リファレンス

CLI 引数	環境変数	デフォルト	説明
--embedding-model	BIGQUERY_EMBEDDING_MODEL	-	必須。 埋め込みモデルのフルパス（project.dataset.model）。起動時に検証されます。
--embedding-tables	BIGQUERY_EMBEDDING_TABLES	-	埋め込み列を含むテーブル（自動検出をスキップします）
--vector-column-contains	BIGQUERY_EMBEDDING_COLUMN_CONTAINS	embedding	埋め込み列を検索するパターン（列名にこの文字列が含まれている必要があります）
--distance-type	BIGQUERY_DISTANCE_TYPE	COSINE	距離尺度：COSINE、EUCLIDEAN、DOT_PRODUCT
--no-vector-search	BIGQUERY_VECTOR_SEARCH_ENABLED=false	有効	ベクトル検索ツールを無効にします

使用例

検出モード - 埋め込みを含むテーブルを検索します：

{
  "query_text": ""
}

検索モード - 意味的類似性検索：

{
  "query_text": "solenoid valve for water",
  "table_path": "my_dataset.products",
  "top_k": "10",
  "select_columns": "name,description,price"
}

必要な権限

ロール	目的
roles/bigquery.dataViewer	テーブルとモデルの読み取り
roles/bigquery.jobUser	BigQuery ジョブの実行
roles/bigquery.metadataViewer	埋め込みテーブルの自動検出（任意）

🏗️ 開発環境のセットアップ

ローカル開発

# Clone and setup
git clone https://github.com/pvoo/bigquery-mcp.git
cd bigquery-mcp
make install  # Setup environment + pre-commit hooks

# Development workflow
make run      # Start server
make test     # Run test suite
make check    # Lint + format + typecheck
make inspect  # Launch MCP inspector

テストと品質

make test                    # Full test suite
pytest tests/test_safety.py  # SQL safety validation tests
pytest tests/test_server.py  # Core server functionality tests
make check                   # Run all quality checks

🔐 認証と権限

認証方法：

1. Application Default Credentials（推奨）：gcloud auth application-default login
2. サービスアカウントキー：--key-file を使用するか、GOOGLE_APPLICATION_CREDENTIALS を設定します

必要な BigQuery 権限：

• bigquery.datasets.get、bigquery.datasets.list
• bigquery.tables.list、bigquery.tables.get
• bigquery.jobs.create、bigquery.data.get

🚨 トラブルシューティング

認証に関する問題：

# Check current auth
gcloud auth application-default print-access-token

# Re-authenticate
gcloud auth application-default login

# Enable BigQuery API
gcloud services enable bigquery.googleapis.com

MCP 接続に関する問題：

• MCP 設定で絶対パスを指定してください
• サーバーを手動でテストします：make run
• プロジェクトとロケーションの環境変数または引数が正しく設定されていることを確認してください

パフォーマンスに関する問題：

• 応答を速くするには {"detailed": false} を使用します
• 検索フィルターを追加します：{"search": "pattern"}
• 大規模なデータセットでは max_results を減らします

💡 使用例

📊 SQL クエリの例

-- Query public datasets
SELECT
    EXTRACT(YEAR FROM pickup_datetime) as year,
    COUNT(*) as trips,
    ROUND(AVG(fare_amount), 2) as avg_fare
FROM `bigquery-public-data.new_york_taxi_trips.tlc_yellow_trips_2020`
WHERE pickup_datetime BETWEEN '2020-01-01' AND '2020-12-31'
GROUP BY year
LIMIT 20

🤖 例：Claude Code サブエージェントでの使用

シナリオ： Claude Code の専門的な BigQuery Table Analyst エージェントを使って、データウェアハウスを自動的に調査し、テーブル間の関係を分析して、構造化された分析結果を得ます。サブエージェントを使うことで、テーブル分析に使うコンテキストをメインスレッドから切り離し、実行可能な分析結果をメインエージェントのスレッドに返して、SQL の作成や分析に活用できます。

セットアップ：

# 1. Clone and configure
git clone https://github.com/pvoo/bigquery-mcp.git
cd bigquery-mcp

# 2. Setup environment
export GCP_PROJECT_ID="your-project-id"
export BIGQUERY_LOCATION="US"
gcloud auth application-default login

# 3. Launch Claude Code
claude-code

使用例：

💬 You: "I need to understand our sales data structure and find tables related to customer orders"

🤖 Claude: I'll use the BigQuery Table Analyst agent to explore your sales datasets and identify relevant tables with their relationships.

[Agent automatically:]
- Lists all datasets to identify sales-related ones
- Explores table schemas with detailed metadata
- Shows actual sample data from key tables
- Discovers join relationships between tables
- Provides ready-to-use SQL queries

エージェントが返す内容：

• テーブルスキーマ（列の説明と型を含む）
• サンプルデータ（プレースホルダーではなく、実際の値を表示）
• 結合関係（動作する SQL の例を含む）
• データ品質に関する分析（NULL 率、鮮度など）
• すぐに実行できる実用的な SQL クエリ

🤝 コントリビューション

コントリビューションを歓迎します！改善に向けたフィードバックをお待ちしています。

クイックスタート：

# Fork on GitHub, then:
git clone https://github.com/yourusername/bigquery-mcp.git
cd bigquery-mcp
make install  # Setup dev environment
make check    # Verify everything works

# Make changes, then:
make test     # Run tests
make check    # Quality checks
# Submit PR!

開発ガイドライン：

• 新機能にはテストを追加します
• ドキュメントを更新します
• 既存のコードスタイルに従います（pre-commit フックによって適用されます）
• すべての品質チェックに合格することを確認します

問題を見つけた場合や機能のリクエストがある場合：

• 🐛 バグ報告： イシューを作成
• 🔧 コードの改善： プルリクエストを送信します
• 📖 ドキュメント： CONTRIBUTING.md をご覧ください

---

🌟 役に立ったら、このリポジトリにスターを付けてください！