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

도구

• 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

개발

Prerequisites

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

Install Dependencies

빌드

Development Mode (Auto-rebuild)

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

디버깅

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP 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 또는 서비스 계정)

종속성 설치

빌드

개발 모드(자동 재빌드)

설치

Claude Desktop에서 사용하려면 서버 설정을 추가하세요.

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

디버깅

MCP 서버는 표준 입출력(stdio)을 통해 통신하므로 디버깅이 어려울 수 있습니다. MCP 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")