BigQuery Analysis

GitHub
BigQuery Analysis MCP Server

Overview

This server is an MCP server for executing SQL queries against Google BigQuery, providing the following features:

  • Query validation (dry run): Verifies if a query is valid and estimates its processing size
  • Safe query execution: Only runs SELECT queries under 1TB (prevents data modifications)
  • JSON-formatted results: Returns query results in structured JSON format

Features

Tools

  • dry_run_query - Perform a dry run of a BigQuery query

    • Validates the query and estimates its processing size
    • Checks query size against the 1TB limit

  • run_query_with_validation - Run a BigQuery query with validation

    • Detects and rejects DML statements (data modification queries)
    • Rejects data processing over 1TB
    • Executes queries that pass validation and returns results

Development

Prerequisites

  • Node.js (v16 or higher)
  • Google Cloud authentication setup (gcloud CLI or service account)

Install Dependencies

npm install

Build

npm run build

Development Mode (Auto-rebuild)

npm run watch

Installation

To use with Claude Desktop, add the server configuration:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bigquery-analysis-server": {
      "command": "/path/to/bigquery-analysis-server/build/index.js"
    }
  }
}

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Authentication Setup

This server uses Google Cloud authentication. Set up authentication using one of the following methods:

  1. Login with gcloud CLI:

    gcloud auth application-default login

  2. Use a service account key:

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

Usage Examples

  1. Dry run a query:

    dry_run_query("SELECT * FROM `bigquery-public-data.samples.shakespeare` LIMIT 10")

  2. Run a query with validation:

    run_query_with_validation("SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus='hamlet' LIMIT 10")
BigQuery Analysis MCP Server (日本語版)

概要

BigQueryでSQLクエリを実行するためのMCPサーバーです。クエリの検証（ドライラン）と実行を行い、1TB以上のデータ処理や変更系クエリ（DML）を防止する安全機能を備えています。

機能

このサーバーはGoogle BigQueryに対してSQLクエリを実行するためのMCPサーバーで、以下の機能を提供します：

  • クエリの検証（ドライラン）：クエリが有効かどうかを確認し、処理サイズを見積もる
  • 安全なクエリ実行：1TB以下のSELECTクエリのみを実行（データ変更を防止）
  • 結果のJSON形式での返却：クエリ結果を構造化されたJSONで返す

機能

ツール

  • dry_run_query - BigQueryクエリのドライラン実行

    • クエリの検証と処理サイズの見積もりを行う
    • 1TBの制限に対してクエリサイズをチェック

  • run_query_with_validation - 検証付きでBigQueryクエリを実行

    • DML文（データ変更クエリ）を検出して拒否
    • 1TB以上のデータ処理を拒否
    • 検証に通過したクエリを実行し結果を返す

開発方法

前提条件

  • Node.js（v16以上）
  • Google Cloud認証設定（gcloud CLIまたはサービスアカウント）

依存関係のインストール

npm install

ビルド

npm run build

開発モード（自動再ビルド）

npm run watch

インストール

Claude Desktopで使用するには、サーバー設定を追加してください：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": ["/path/to/bigquery-server/build/index.js"]
    }
  }
}

デバッグ

MCPサーバーは標準入出力（stdio）を介して通信するため、デバッグが難しい場合があります。MCP Inspectorの使用をお勧めします：

npm run inspector

InspectorはブラウザでデバッグツールにアクセスするためのURLを提供します。

認証設定

このサーバーはGoogle Cloud認証情報を使用します。以下のいずれかの方法で認証を設定してください：

  1. gcloud CLIでログイン：

    gcloud auth application-default login

  2. サービスアカウントキーを使用：

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

使用例

  1. クエリのドライラン：

    dry_run_query("SELECT * FROM `bigquery-public-data.samples.shakespeare` LIMIT 10")

  2. 検証付きクエリ実行：

    run_query_with_validation("SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus='hamlet' LIMIT 10")