BigQuery Validator

mcp-bigquery

MIT license PyPI - Downloads

The mcp-bigquery package provides a minimal MCP server for BigQuery SQL validation and dry-run analysis. This server provides exactly two tools for validating and analyzing BigQuery SQL queries without executing them.

** IMPORTANT: This server does NOT execute queries. All operations are dry-run only. Cost estimates are approximations based on bytes processed.**

Features

SQL Validation: Check BigQuery SQL syntax without running queries
Dry-Run Analysis: Get cost estimates, referenced tables, and schema preview
Parameter Support: Validate parameterized queries
Cost Estimation: Calculate USD estimates based on bytes processed

Quick Start

Prerequisites

Python 3.10+
Google Cloud SDK with BigQuery API enabled
Application Default Credentials configured

Installation

From PyPI (Recommended)

# Install from PyPI
pip install mcp-bigquery

# Or with uv
uv pip install mcp-bigquery

From Source

# Clone the repository
git clone https://github.com/caron14/mcp-bigquery.git
cd mcp-bigquery

# Install with uv (recommended)
uv pip install -e .

# Or install with pip
pip install -e .

Authentication

Set up Application Default Credentials:

gcloud auth application-default login

Or use a service account key:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Configuration

Environment Variables

Variable	Description	Default
`BQ_PROJECT`	GCP project ID	From ADC
`BQ_LOCATION`	BigQuery location (e.g., US, EU, asia-northeast1)	None
`SAFE_PRICE_PER_TIB`	Default price per TiB for cost estimation	5.0

Claude Code Integration

Add to your Claude Code configuration:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "your-gcp-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "5.0"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "python",
      "args": ["-m", "mcp_bigquery"],
      "env": {
        "BQ_PROJECT": "your-gcp-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "5.0"
      }
    }
  }
}

Tools

bq_validate_sql

Validate BigQuery SQL syntax without executing the query.

Input:

{
  "sql": "SELECT * FROM dataset.table WHERE id = @id",
  "params": {"id": "123"}  // Optional
}

Success Response:

{
  "isValid": true
}

Error Response:

{
  "isValid": false,
  "error": {
    "code": "INVALID_SQL",
    "message": "Syntax error at [3:15]",
    "location": {
      "line": 3,
      "column": 15
    },
    "details": [...]  // Optional
  }
}

bq_dry_run_sql

Perform a dry-run to get cost estimates and metadata without executing the query.

Input:

{
  "sql": "SELECT * FROM dataset.table",
  "params": {"id": "123"},  // Optional
  "pricePerTiB": 6.0  // Optional, overrides default
}

Success Response:

{
  "totalBytesProcessed": 1073741824,
  "usdEstimate": 0.005,
  "referencedTables": [
    {
      "project": "my-project",
      "dataset": "my_dataset",
      "table": "my_table"
    }
  ],
  "schemaPreview": [
    {
      "name": "id",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "created_at",
      "type": "TIMESTAMP",
      "mode": "REQUIRED"
    }
  ]
}

Error Response:

{
  "error": {
    "code": "INVALID_SQL",
    "message": "Table not found: dataset.table",
    "details": [...]  // Optional
  }
}

Examples

Validate a Simple Query

# Tool: bq_validate_sql
{
  "sql": "SELECT 1"
}
# Returns: {"isValid": true}

Validate with Parameters

# Tool: bq_validate_sql
{
  "sql": "SELECT * FROM users WHERE name = @name AND age > @age",
  "params": {
    "name": "Alice",
    "age": 25
  }
}

Get Cost Estimate

# Tool: bq_dry_run_sql
{
  "sql": "SELECT * FROM `bigquery-public-data.samples.shakespeare`",
  "pricePerTiB": 5.0
}
# Returns bytes processed, USD estimate, and schema

Analyze Complex Query

# Tool: bq_dry_run_sql
{
  "sql": """
    WITH user_stats AS (
      SELECT user_id, COUNT(*) as order_count
      FROM orders
      GROUP BY user_id
    )
    SELECT * FROM user_stats WHERE order_count > 10
  """
}

Testing

Run tests with pytest:

# Run all tests (requires BigQuery credentials)
pytest tests/

# Run only tests that don't require credentials
pytest tests/test_min.py::TestWithoutCredentials

Development

# Install development dependencies
uv pip install -e ".[dev]"

# Run the server locally
python -m mcp_bigquery

# Or using the console script
mcp-bigquery

Limitations

No Query Execution: This server only performs dry-runs and validation
Cost Estimates: USD estimates are approximations based on bytes processed
Parameter Types: Initial implementation treats all parameters as STRING type
Cache Disabled: Queries always run with use_query_cache=False for accurate estimates

License

MIT

Changelog

0.2.1 (2025-08-16)

Fixed GitHub Pages documentation layout issues
Enhanced MkDocs Material theme compatibility
Improved documentation dependencies and build process
Added site/ directory to .gitignore
Simplified documentation layout for better compatibility

0.2.0 (2025-08-16)

Code quality improvements with pre-commit hooks
Enhanced development setup with Black, Ruff, isort, and mypy
Improved CI/CD pipeline
Documentation enhancements

0.1.0 (2025-08-16)

Initial release
Renamed from mcp-bigquery-dryrun to mcp-bigquery
SQL validation tool (bq_validate_sql)
Dry-run analysis tool (bq_dry_run_sql)
Cost estimation based on bytes processed
Support for parameterized queries

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Enables validation and dry-run analysis of BigQuery SQL queries without execution. Provides cost estimates, schema previews, and syntax validation for BigQuery queries.

Related Resources

Reddit Discussion about this server

Related MCP Servers

MySQL MCP Server
designcomputer
A
security
A
license
A
quality
Allows AI assistants to list tables, read data, and execute SQL queries through a controlled interface, making database exploration and analysis safer and more structured.
Last updated -
1
768
Python
MIT License
BigQuery Analysis MCP Server
gotalab
-
security
F
license
-
quality
A server that enables executing and validating SQL queries against Google BigQuery with safety features that prevent data modifications and excessive processing.
Last updated -
1
TypeScript
MySQL MCP
Liu-creators
-
security
F
license
-
quality
A tool that provides simple API to execute SQL queries and manage MySQL databases, designed to integrate with Cursor IDE for AI assistants to directly perform database operations.
Last updated -
Python
MCP Server
sathwikabbaraju
-
security
F
license
-
quality
Manages query validation, database connection, and security for a system that transforms SQL databases into interactive dashboards using natural language queries.
Last updated -
Python

View all related MCP servers

BigQuery Validator

mcp-bigquery

Features

Quick Start

Prerequisites

Installation

From PyPI (Recommended)

From Source

Authentication

Configuration

Environment Variables

Claude Code Integration

Tools

bq_validate_sql

bq_dry_run_sql

Examples

Validate a Simple Query

Validate with Parameters

Get Cost Estimate

Analyze Complex Query

Testing

Development

Limitations

License

Changelog

0.2.1 (2025-08-16)

0.2.0 (2025-08-16)

0.1.0 (2025-08-16)

Tools

Related Resources

Related MCP Servers

MySQL MCP Server

BigQuery Analysis MCP Server

MySQL MCP

MCP Server

New MCP Servers

MCP directory API