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 (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

overview

This is an MCP server for executing SQL queries in BigQuery. It validates (dry runs) and executes queries, and has safety features that prevent data processing and modification queries (DML) of more than 1TB.

function

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

• Query validation (dry run): Check if the query is valid and estimate the processing size

• Safe query execution: Only execute SELECT queries of 1TB or less (prevent data modification)

• Return results in JSON format: Return query results in structured JSON.

function

tool

• dry_run_query - Execute a dry run of a BigQuery query

  • Validate queries and estimate processing size

  • Check query size against 1TB limit

• run_query_with_validation - Run a BigQuery query with validation

  • Detect and reject DML statements (data modification queries)

  • Refuse to process data over 1TB

  • Executes queries that pass validation and returns the results

Development method

Prerequisites

• Node.js (v16 and above)

• Google Cloud authentication settings (gcloud CLI or service account)

Installing dependencies

npm install

Build

npm run build

Development mode (auto-rebuild)

npm run watch

install

To use it with Claude Desktop, add your server configuration:

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"]
    }
  }
}

debug

MCP servers can be difficult to debug because they communicate via standard input/output (stdio). We recommend using MCP Inspector :

npm run inspector

Inspector provides a URL to access the debugging tools in your browser.

Authentication Settings

This server uses Google Cloud credentials, please set up authentication in one of the following ways:

1. Log in 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 Example

1. Dry run the query:

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

2. Query execution with validation:

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