BigQuery Analysis MCP Server

Overview

The BigQuery Analysis MCP Server is designed to execute SQL queries against Google BigQuery, offering 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, preventing data modifications.
• JSON-formatted results: Returns query results in structured JSON format.

Features

Tools

• dry_run_query: Performs 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: Runs 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:

   shell gcloud auth application-default login

2. Use a service account key:

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

Usage Examples

1. Dry run a query:

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

2. Run a query with validation:

   shell 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でログイン：

   shell gcloud auth application-default login

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

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

使用例

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

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

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

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