Skip to main content
Glama
Sign In
enesjakozh
gotalab

BigQuery Analysis MCP Server

by gotalab
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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

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

NameRequiredDescriptionDefault
queryYesThe SQL query to dry run
projectIdNoGoogle Cloud project ID (optional, uses default if not provided)

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It does disclose the key behavioral trait that the query is not actually executed (dry run) and that a size estimate is returned, which is meaningful. It omits permissions requirements, cost implications, and how errors are surfaced.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence with the action and both outcomes front-loaded; nothing is redundant. It is arguably too sparse rather than wasteful, which keeps it just shy of 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description should describe the shape of the result (validation errors vs. bytes-processed estimate, schema preview). It only gestures at 'estimate its size', leaving the return value under-specified for an agent that must interpret the dry-run result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented ('query', 'projectId' with default behavior). The description adds no syntax, format, or dialect detail beyond the schema, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('dry run of a BigQuery query') and names both outcomes: validity check and size estimate. It implicitly contrasts with the only sibling, run_query_with_validation, by being the non-executing variant, but never names the sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'to check if it's valid' hints at the pre-flight validation use case, which is the correct context for choosing this over run_query_with_validation. However, there is no explicit when-to-use/when-not guidance, no mention that this avoids execution cost, and no named alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_query_with_validationB

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

NameRequiredDescriptionDefault
queryYesThe SQL query to run (only SELECT queries are allowed)
projectIdNoGoogle Cloud project ID (optional, uses default if not provided)
maxResultsNoMaximum number of results to return (default: 100)

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses that validation fails for queries over 1 TB or containing DML, but it omits authentication needs, billing implications, whether the query actually executes after validation, and what the response looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no wasted words. The core action and validation constraints are stated immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple three-parameter tool with a fully described schema, the description covers the main execution and validation behavior. However, it does not explain return values despite there being no output schema, and it does not mention the closely related dry_run_query sibling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are documented in the schema. The description does not add meaning beyond the schema for query, projectId, or maxResults, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: it runs a BigQuery query and performs dry-run validation. It clearly defines the validation scope, including failure thresholds for size and DML, but it does not explicitly distinguish this tool from the sibling dry_run_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives constraints such as the 1 TB limit and DML rejection, which imply this is for safe SELECT execution. However, it provides no explicit guidance on when to use this tool versus dry_run_query, nor does it explain when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 2 tool updatesv0.1.0
    • First observeddry_run_query
    • First observedrun_query_with_validation
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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 issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP PostgreSQL Server

    Maxim2324
    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
    425 npm
    1
    MIT

  • BigQuery Validator

    caron14
    A
    license
    B
    quality
    B
    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
    30 PyPI
    1
    MIT

  • bq-readonly-mcp

    mariadb-RupeshBiswas
    A
    license
    Not graded
    quality
    B
    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.
    1
    MIT

  • bigquery-mcp

    aicayzer
    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

Appeared in Searches