MCP BigQuery¶

Overview¶

The mcp-bigquery package provides a comprehensive MCP server for BigQuery SQL validation, dry-run analysis, query structure analysis, and schema discovery. This server provides eleven tools for validating, analyzing, understanding BigQuery SQL queries, and exploring BigQuery schemas without executing queries.

Key Features¶

🔍 SQL Analysis & Validation¶

• SQL Validation: Check BigQuery SQL syntax without running queries
• Dry-Run Analysis: Get cost estimates, referenced tables, and schema preview
• Query Structure Analysis: Analyze SQL complexity, JOINs, CTEs, and query patterns
• Dependency Extraction: Extract table and column dependencies from queries
• Enhanced Syntax Validation: Detailed error reporting with suggestions → SQL Analysis Guide

📊 Schema Discovery & Metadata (v0.4.0)¶

• Dataset Explorer: List and explore datasets in your BigQuery project
• Table Browser: Browse tables with metadata, partitioning, and clustering info
• Schema Inspector: Get detailed table schemas with nested field support
• INFORMATION_SCHEMA Access: Safe querying of BigQuery metadata views
• Comprehensive Table Info: Access all table metadata including encryption and time travel → Schema Discovery Guide

🚀 Performance Analysis¶

• Query Performance Scoring: Analyze query performance without execution
• Optimization Suggestions: Get actionable recommendations for query improvements
• Cost-Benefit Analysis: Compare costs before and after optimizations → Performance Guide

🏷️ Additional Features¶

• Parameter Support: Validate parameterized queries
• Safe Operations: All operations are dry-run only, no query execution
• BigQuery-Specific: Support for ARRAY, STRUCT, and other BigQuery features → Advanced Features

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

{
  "tool": "bq_list_tables",
  "arguments": {
    "dataset_id": "samples",
    "project_id": "bigquery-public-data"
  }
}

{
  "dataset_id": "samples",
  "table_count": 3,
  "tables": [
    {
      "table_id": "shakespeare",
      "table_type": "TABLE",
      "num_rows": 164656,
      "num_bytes": 6432064
    }
  ]
}

{
  "tool": "bq_analyze_query_performance",
  "arguments": {
    "sql": "SELECT * FROM large_table WHERE date > '2024-01-01'"
  }
}

{
  "performance_score": 65,
  "performance_rating": "GOOD",
  "optimization_suggestions": [
    {
      "type": "SELECT_STAR",
      "severity": "MEDIUM",
      "recommendation": "Select only needed columns"
    }
  ]
}

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.