AI导哈

BigQuery 查询 MCP 服务器

BigQuery Analysis MCP Server 是一款面向 AI 助手和开发者的 MCP 服务器，用于对 Google BigQuery 执行带验证的 SELECT SQL 查询（支持 dry run 预估处理量），并以 JSON 格式返回结果，适用于安全高效的大数据查询与分析场景。

  • by gotalab
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 gotalab/bigquery-analysis-mcp-server

使用说明

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 22.23.4+, 24.22.1+, or 26.12.1+ (use the latest patch of a supported release line)
  • pnpm 12.4.2 (pinned in package.json)
  • Google Cloud authentication setup (gcloud CLI or service account)

Install Dependencies

pnpm install --frozen-lockfile

Test

pnpm test

Build

pnpm run build

Development Mode (Auto-rebuild)

pnpm 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:

pnpm 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 22.23.4以上、24.22.1以上、または26.12.1以上（サポート中の系列の最新パッチを使用）
  • pnpm 12.4.2（package.jsonで固定）
  • Google Cloud認証設定（gcloud CLIまたはサービスアカウント）

依存関係のインストール

pnpm install --frozen-lockfile

テスト

pnpm test

ビルド

pnpm run build

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

pnpm 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の使用をお勧めします：

pnpm 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")

相关 MCP