MCP BigQuery¶

Overview¶

The mcp-bigquery package provides a Model Context Protocol (MCP) server that enables safe BigQuery SQL validation and analysis without executing queries. Perfect for development workflows, CI/CD pipelines, and cost optimization.

Key Features¶

✅ SQL Validation¶

Validate BigQuery SQL syntax without running queries. Catch errors early in your development workflow. → Validation Guide

💰 Cost Estimation¶

Get accurate cost estimates based on bytes processed. Optimize queries before execution. → Cost Estimation

📊 Schema Preview¶

Preview result schemas and referenced tables without accessing actual data. → Dry-Run Analysis

🏷️ Parameter Support¶

Validate parameterized queries with full support for query parameters. → Using Parameters

Quick Example¶

{
  "tool": "bq_validate_sql",
  "arguments": {
    "sql": "SELECT * FROM `project.dataset.table` WHERE date = @date",
    "params": {"date": "2024-01-01"}
  }
}

{
  "isValid": true
}

{
  "tool": "bq_dry_run_sql",
  "arguments": {
    "sql": "SELECT * FROM `bigquery-public-data.samples.shakespeare`"
  }
}

{
  "totalBytesProcessed": 1073741824,
  "usdEstimate": 0.005,
  "referencedTables": [
    {
      "project": "bigquery-public-data",
      "dataset": "samples",
      "table": "shakespeare"
    }
  ]
}

Installation¶

Install from PyPI:

pip install mcp-bigquery

Or with uv:

uv pip install mcp-bigquery

Get Started

Use Cases¶

Development Workflow¶

• Validate SQL syntax during development
• Estimate query costs before execution
• Preview result schemas without running queries
• Test parameterized queries safely

CI/CD Integration¶

• Automated SQL validation in pull requests
• Cost threshold checks in pipelines
• Schema compatibility verification
• Query optimization validation

Cost Optimization¶

• Identify expensive queries before execution
• Compare cost estimates for different approaches
• Monitor query complexity trends
• Optimize data access patterns

Documentation¶

🚀 Installation¶

Setup, authentication, and configuration

📖 Usage Guide¶

SQL validation, dry-run analysis, and best practices

📋 API Reference¶

Complete tool documentation and schemas

💻 Examples¶

Real-world queries and patterns

Support¶

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Source Code: GitHub Repository

License¶

This project is licensed under the MIT License. See the LICENSE file for details.