Skip to main content
Glama
BigQuery Analysis MCP Server

BigQuery Analysis MCP Server

by gotalab

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

Related MCP server: BigQuery Validator

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

Available Tools

2 tools
dry_run_queryB

Perform a dry run of a BigQuery query to check if it's valid and estimate its size

Inputs: query (required), projectId.

run_query_with_validationB

Run a BigQuery query with dry run validation (fails if query exceeds 1 TB or contains DML statements)

Inputs: query (required), projectId, maxResults.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 2 tools

    Disambiguation4/5

    The two tools have mostly distinct roles: one validates only, the other executes with built-in validation. There is mild overlap since run_query_with_validation internally performs a dry run, so an agent might briefly hesitate, but the outcome differences (no execution vs. execution) make the choice clear.

    Naming Consistency4/5

    Both names use snake_case and start with an action verb, which is consistent. However, 'dry_run_query' is a compact noun-style phrase while 'run_query_with_validation' is a longer descriptive phrase, a minor stylistic deviation.

    Tool Count3/5

    Two tools is thin for a server framed as 'BigQuery Analysis' — analysis usually implies exploration beyond validate/execute. The pair is coherent but leaves the surface feeling minimal.

    Completeness2/5

    There is no way to discover datasets, tables, or schemas, and no tool to run queries that legitimately contain DML or exceed 1 TB. Agents doing real analysis will hit dead ends when they need metadata or unrestricted execution.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A server that connects to PostgreSQL databases and provides tools for safely exploring schemas, running read-only SQL queries, and performing data analysis with pre-built templates.
      6
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables validation and dry-run analysis of BigQuery SQL queries without execution. Provides cost estimates, schema previews, and syntax validation for BigQuery queries.
      9
      60 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A read-only BigQuery MCP server with auto-LIMIT injection, dry-run cost guard, and ADC authentication. Allows safe SQL querying of BigQuery by LLMs without risk of data modification or unexpected costs.
      22 PyPI
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for secure BigQuery access across multiple Google Cloud projects, enabling querying, schema exploration, and data analysis with SQL validation and read-only controls.
      2
      MIT