MCP BigQuery¶

Overview¶

The mcp-bigquery package provides a comprehensive MCP server for BigQuery SQL validation, dry-run analysis, dependency analysis, and schema discovery. This server provides eight tools for validating, analyzing, 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
• Dependency Extraction: Extract table and column dependencies from queries
• Enhanced Syntax Validation: Detailed error reporting with suggestions → SQL Analysis Guide

📊 Schema Explorer & Metadata (updated v0.4.2)¶

• Dataset Explorer: List and explore datasets in your BigQuery project
• Table Browser: Browse tables with metadata, partitioning, and clustering info via dedicated formatters
• Schema Inspector: Get detailed table schemas with nested field support
• Comprehensive Table Info: Access all table metadata including encryption and time travel using the new modular helpers → Schema Discovery 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
• Structured Logging: CLI exposes --verbose/--quiet and --json-logs flags governed by logging_config → 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_extract_dependencies",
  "arguments": {
    "sql": "SELECT u.name, o.total FROM users u JOIN orders o ON u.id = o.user_id"
  }
}

{
  "tables": [
    {
      "full_name": "users"
    },
    {
      "full_name": "orders"
    }
  ],
  "columns": ["name", "total", "id", "user_id"]
}

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
• Optimize data access patterns

Documentation¶

🚀 Installation¶

Setup, authentication, and configuration

📖 Usage Guide¶

SQL validation, dry-run analysis, and best practices

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.