MCP Bigquery

🚀 mcp-bigquery

mcp-bigquery パッケージは、BigQuery SQLの検証、ドライラン分析、およびクエリ構造分析を行う包括的なMCPサーバーを提供します。このサーバーは、クエリを実行せずにBigQuery SQLクエリの検証、分析、および理解を行うための5つのツールを提供します。

⚠️ 重要提示

このサーバーはクエリを実行しません。すべての操作はドライランのみです。コスト見積もりは、処理されたバイト数に基づく概算です。

🚀 クイックスタート

前提条件

• Python 3.10以上
• BigQuery APIが有効になっているGoogle Cloud SDK
• 構成されたアプリケーションのデフォルト資格情報

インストール

PyPIからのインストール (推奨)

# PyPIからインストール
pip install mcp-bigquery

# またはuvを使用する場合
uv pip install mcp-bigquery

ソースからのインストール

# リポジトリをクローン
git clone https://github.com/caron14/mcp-bigquery.git
cd mcp-bigquery

# uvでインストール (推奨)
uv pip install -e .

# またはpipでインストール
pip install -e .

認証

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

gcloud auth application-default login

または、サービスアカウントキーを使用します。

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

設定

環境変数

Claude Codeの統合

Claude Codeの設定に追加します。

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "your-gcp-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "5.0"
      }
    }
  }
}

または、ソースからインストールした場合は次のようにします。

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "python",
      "args": ["-m", "mcp_bigquery"],
      "env": {
        "BQ_PROJECT": "your-gcp-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "5.0"
      }
    }
  }
}

✨ 主な機能

• SQL検証：クエリを実行せずにBigQuery SQL構文をチェックします。
• ドライラン分析：コスト見積もり、参照されるテーブル、およびスキーマのプレビューを取得します。
• クエリ構造分析：SQLの複雑さ、JOIN、CTE、およびクエリパターンを分析します。
• 依存関係抽出：クエリからテーブルと列の依存関係を抽出します。
• 拡張構文検証：提案付きの詳細なエラーレポートを提供します。
• パラメータサポート：パラメータ化されたクエリを検証します。
• コスト見積もり：処理されたバイト数に基づいてUSDの見積もりを計算します。

💻 使用例

基本的な使用法

単純なクエリの検証

# Tool: bq_validate_sql
{
  "sql": "SELECT 1"
}
# Returns: {"isValid": true}

パラメータ付きの検証

# Tool: bq_validate_sql
{
  "sql": "SELECT * FROM users WHERE name = @name AND age > @age",
  "params": {
    "name": "Alice",
    "age": 25
  }
}

コスト見積もりの取得

# Tool: bq_dry_run_sql
{
  "sql": "SELECT * FROM `bigquery-public-data.samples.shakespeare`",
  "pricePerTiB": 5.0
}
# Returns bytes processed, USD estimate, and schema

複雑なクエリの分析

# Tool: bq_dry_run_sql
{
  "sql": """
    WITH user_stats AS (
      SELECT user_id, COUNT(*) as order_count
      FROM orders
      GROUP BY user_id
    )
    SELECT * FROM user_stats WHERE order_count > 10
  """
}

クエリ構造の分析

# Tool: bq_analyze_query_structure
{
  "sql": """
    WITH ranked_products AS (
      SELECT 
        p.name,
        p.price,
        ROW_NUMBER() OVER (PARTITION BY p.category ORDER BY p.price DESC) as rank
      FROM products p
      JOIN categories c ON p.category_id = c.id
    )
    SELECT * FROM ranked_products WHERE rank <= 3
  """
}
# Returns: Complex query analysis with CTE, window functions, and JOINs

クエリの依存関係の抽出

# Tool: bq_extract_dependencies
{
  "sql": "SELECT u.name, u.email, o.total FROM users u LEFT JOIN orders o ON u.id = o.user_id"
}
# Returns: Tables (users, orders) and columns (name, email, total, id, user_id)

拡張構文検証

# Tool: bq_validate_query_syntax
{
  "sql": "SELECT * FROM users WHERE name = 'John' LIMIT 10"
}
# Returns: Validation with performance warnings and suggestions

BigQuery固有の構文の検証

# Tool: bq_validate_query_syntax
{
  "sql": "SELECT ARRAY[1, 2, 3] as numbers, STRUCT('John' as name, 25 as age) as person"
}
# Returns: Validation recognizing BigQuery ARRAY and STRUCT syntax

📚 ドキュメント

ツールの説明

bq_validate_sql

クエリを実行せずにBigQuery SQL構文を検証します。

入力:

{
  "sql": "SELECT * FROM dataset.table WHERE id = @id",
  "params": {"id": "123"}  // オプション
}

成功レスポンス:

{
  "isValid": true
}

エラーレスポンス:

{
  "isValid": false,
  "error": {
    "code": "INVALID_SQL",
    "message": "Syntax error at [3:15]",
    "location": {
      "line": 3,
      "column": 15
    },
    "details": [...]  // オプション
  }
}

bq_dry_run_sql

クエリを実行せずにコスト見積もりとメタデータを取得するためのドライランを実行します。

入力:

{
  "sql": "SELECT * FROM dataset.table",
  "params": {"id": "123"},  // オプション
  "pricePerTiB": 6.0  // オプション、デフォルトを上書き
}

成功レスポンス:

{
  "totalBytesProcessed": 1073741824,
  "usdEstimate": 0.005,
  "referencedTables": [
    {
      "project": "my-project",
      "dataset": "my_dataset",
      "table": "my_table"
    }
  ],
  "schemaPreview": [
    {
      "name": "id",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP",
      "mode": "REQUIRED"
    }
  ]
}

エラーレスポンス:

{
  "error": {
    "code": "INVALID_SQL",
    "message": "Table not found: dataset.table",
    "details": [...]  // オプション
  }
}

bq_analyze_query_structure

BigQuery SQLクエリの構造と複雑さを分析します。

入力:

{
  "sql": "SELECT u.name, COUNT(*) FROM users u LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.name",
  "params": {}  // オプション
}

成功レスポンス:

{
  "query_type": "SELECT",
  "has_joins": true,
  "has_subqueries": false,
  "has_cte": false,
  "has_aggregations": true,
  "has_window_functions": false,
  "has_union": false,
  "table_count": 2,
  "complexity_score": 15,
  "join_types": ["LEFT"],
  "functions_used": ["COUNT"]
}

bq_extract_dependencies

BigQuery SQLからテーブルと列の依存関係を抽出します。

入力:

{
  "sql": "SELECT u.name, u.email FROM users u WHERE u.created_at > '2023-01-01'",
  "params": {}  // オプション
}

成功レスポンス:

{
  "tables": [
    {
      "project": null,
      "dataset": "users",
      "table": "u",
      "full_name": "users.u"
    }
  ],
  "columns": ["created_at", "email", "name"],
  "dependency_graph": {
    "users.u": ["created_at", "email", "name"]
  },
  "table_count": 1,
  "column_count": 3
}

bq_validate_query_syntax

詳細なエラーレポートを伴う拡張構文検証を行います。

入力:

{
  "sql": "SELECT * FROM users WHERE name = 'John' LIMIT 10",
  "params": {}  // オプション
}

成功レスポンス:

{
  "is_valid": true,
  "issues": [
    {
      "type": "performance",
      "message": "SELECT * may impact performance - consider specifying columns",
      "severity": "warning"
    },
    {
      "type": "consistency",
      "message": "LIMIT without ORDER BY may return inconsistent results",
      "severity": "warning"
    }
  ],
  "suggestions": [
    "Specify exact columns needed instead of using SELECT *",
    "Add ORDER BY clause before LIMIT for consistent results"
  ],
  "bigquery_specific": {
    "uses_legacy_sql": false,
    "has_array_syntax": false,
    "has_struct_syntax": false
  }
}

🔧 技術詳細

テスト

pytestを使用してテストを実行します。

# すべてのテストを実行 (BigQueryの資格情報が必要)
pytest tests/

# 資格情報を必要としないテストのみを実行
pytest tests/test_min.py::TestWithoutCredentials

開発

# 開発用の依存関係をインストール
uv pip install -e ".[dev]"

# サーバーをローカルで実行
python -m mcp_bigquery

# またはコンソールスクリプトを使用
mcp-bigquery

制限事項

• クエリ実行なし：このサーバーはドライランと検証のみを行います。
• コスト見積もり：USDの見積もりは、処理されたバイト数に基づく概算です。
• パラメータタイプ：初期実装では、すべてのパラメータをSTRINGタイプとして扱います。
• キャッシュ無効：正確な見積もりのために、クエリは常に use_query_cache=False で実行されます。

📄 ライセンス

MIT

変更履歴

0.3.0 (2025-08-17)

• 新しいツール：包括的なクエリ分析のための3つの新しいSQL分析ツールを追加しました。
• bq_analyze_query_structure：SQLの複雑さ、JOIN、CTE、ウィンドウ関数を分析し、複雑度スコアを計算します。
• bq_extract_dependencies：依存関係グラフマッピングでテーブルと列の依存関係を抽出します。
• bq_validate_query_syntax：詳細なエラーレポートと提案付きの拡張構文検証を行います。
• SQL分析エンジン：包括的なBigQuery SQL解析機能を持つ新しいSQLAnalyzerクラスを追加しました。
• BigQuery固有の機能：ARRAY/STRUCT構文、レガシーSQLパターン、およびBigQuery固有の検証を検出します。
• 下位互換性：すべての既存のツール (bq_validate_sql、bq_dry_run_sql) は変更されていません。
• 拡張ドキュメント：5つのツールすべての包括的な例を含むように更新しました。

0.2.1 (2025-08-16)

• GitHub Pagesのドキュメントレイアウトの問題を修正しました。
• MkDocs Materialテーマの互換性を強化しました。
• ドキュメントの依存関係とビルドプロセスを改善しました。
• .gitignoreにsite/ディレクトリを追加しました。
• 互換性向上のためにドキュメントレイアウトを簡素化しました。

0.2.0 (2025-08-16)

• pre-commitフックを使用してコード品質を向上させました。
• Black、Ruff、isort、およびmypyを使用して開発環境を強化しました。
• CI/CDパイプラインを改善しました。
• ドキュメントを強化しました。

0.1.0 (2025-08-16)

• 最初のリリースです。
• mcp-bigquery-dryrunからmcp-bigqueryに名前を変更しました。
• SQL検証ツール (bq_validate_sql)
• ドライラン分析ツール (bq_dry_run_sql)
• 処理されたバイト数に基づくコスト見積もり
• パラメータ化されたクエリのサポート