Skip to main content

mcp-bigquery

MCP BigQuery Logo

Safe BigQuery exploration through Model Context Protocol

MIT License PyPI Version Python Support Downloads

Documentation | Quick Start | Tools | Examples


📌 What is this?

mcp-bigquery is an MCP (Model Context Protocol) server that enables AI assistants like Claude to safely interact with Google BigQuery.

🎯 Key Features

graph LR
    A[AI Assistant] -->|MCP Protocol| B[mcp-bigquery]
    B -->|Dry-run Only| C[BigQuery API]
    B -.->|❌ Never Executes| D[Actual Query Execution]
  • 🛡️ 100% Safe: All operations are dry-run only (never executes queries)
  • 💰 Cost Transparency: See costs before running any query
  • 🔍 Complete Analysis: Analyze dependencies and validate SQL syntax
  • 📊 Schema Explorer: Browse datasets, tables, and columns with ease

⚡ Why use mcp-bigquery?

Problem Solution with mcp-bigquery
💸 Accidentally running expensive queries Check costs before execution
🐛 Wasting time on SQL errors Detect syntax errors before running
🗺️ Unknown table structures Easily explore schemas
⚠️ AI executing dangerous operations Everything is read-only and safe

🚀 Quick Start (4 minutes)

Step 1: Install (1 minute)

pip install mcp-bigquery

Step 2: Authenticate with Google Cloud (2 minutes)

# For personal accounts
gcloud auth application-default login

# For service accounts
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Step 3: Configure Claude Desktop (1 minute)

Open your Claude Desktop config:

  • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "your-gcp-project-id"  // ← Replace with your project ID
      }
    }
  }
}

Step 4: Test It!

Restart Claude Desktop and try these questions:

"What datasets are available in my BigQuery project?"
"Can you estimate the cost of: SELECT * FROM dataset.table"
"Show me the schema for the users table"

🛠️ Available Tools

📝 SQL Validation & Analysis

Tool Purpose When to Use
bq_validate_sql Check SQL syntax Before running any query
bq_dry_run_sql Get cost estimates & metadata 💰 To check costs
bq_extract_dependencies Extract table dependencies To understand data lineage
bq_validate_query_syntax Detailed error analysis To debug SQL errors

🔍 Schema Discovery

Tool Purpose When to Use
bq_list_datasets List all datasets To explore your project
bq_list_tables List tables with partitioning info To browse a dataset
bq_describe_table Get detailed table schema To understand columns
bq_get_table_info Complete table metadata To get statistics
bq_preview_table Preview table data (cost-free) To view sample records without scan costs

💡 Real-World Examples

Example 1: Check Costs Before Running

# Before running an expensive query...
query = "SELECT * FROM `bigquery-public-data.github_repos.commits`"

# First, check the cost
result = bq_dry_run_sql(sql=query)
print(f"Estimated cost: ${result['usdEstimate']}")
print(f"Data processed: {result['totalBytesProcessed'] / 1e9:.2f} GB")

# Output:
# Estimated cost: $12.50
# Data processed: 2500.00 GB

Example 2: Understand Table Structure

# Check table schema
result = bq_describe_table(
    dataset_id="your_dataset",
    table_id="users"
)

# Output:
# ├── user_id (INTEGER, REQUIRED)
# ├── email (STRING, NULLABLE)
# ├── created_at (TIMESTAMP, REQUIRED)
# └── profile (RECORD, REPEATED)
#     ├── name (STRING)
#     └── age (INTEGER)

Example 3: Track Data Dependencies

# Understand query dependencies
query = """
WITH user_stats AS (
  SELECT user_id, COUNT(*) as order_count
  FROM orders
  GROUP BY user_id
)
SELECT u.name, s.order_count
FROM users u
JOIN user_stats s ON u.id = s.user_id
"""

result = bq_extract_dependencies(sql=query)

# Output:
# Tables: ['orders', 'users']
# Columns: ['user_id', 'name', 'id']
# Dependency Graph:
#   orders → user_stats → final_result
#   users → final_result

🎨 How It Works

Your Code ← → Claude/AI Assistant
                   ↓
            MCP Protocol
                   ↓
            mcp-bigquery
                   ↓
         BigQuery API (Dry-run)
                   ↓
             BigQuery
      (Never executes actual queries)

⚙️ Configuration

Environment Variables

export BQ_PROJECT="my-project"        # GCP Project ID (required)
export BQ_LOCATION="asia-northeast1"  # Region (optional)
export SAFE_PRICE_PER_TIB="5.0"      # Price per TiB (default: $5)
export LOG_LEVEL="INFO"              # Optional log level override
export MCP_BQ_ENABLE_PREVIEW="true"  # Opt-in to enable bq_preview_table (default: false)

Full Claude Desktop Configuration

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "my-production-project",
        "BQ_LOCATION": "asia-northeast1",
        "SAFE_PRICE_PER_TIB": "6.0",
        "LOG_LEVEL": "WARNING",
        "MCP_BQ_ENABLE_PREVIEW": "true"
      }
    }
  }
}

🔧 Troubleshooting

Common Issues & Solutions

❌ Authentication Error

Error: Could not automatically determine credentials

Solution:

gcloud auth application-default login

❌ Permission Error

Error: User does not have bigquery.tables.get permission

Solution: Grant BigQuery Data Viewer role

gcloud projects add-iam-policy-binding YOUR_PROJECT \
  --member="user:your-email@example.com" \
  --role="roles/bigquery.dataViewer"

❌ Project Not Set

Error: Project ID is required

Solution: Set BQ_PROJECT in your configuration

Debug Mode

If issues persist, enable debug mode:

{
  "env": {
    "LOG_LEVEL": "INFO",
    "BQ_PROJECT": "your-project"
  }
}

📚 Learn More

Getting Started

For Developers

🚦 Project Status

Version Release Date Key Features
v0.7.0 2026-06-21 Cost-free table preview tool (bq_preview_table) and security opt-in
v0.6.0 2026-06-21 Thread-safe caching, recursive AST queries, backoff retries, mapping exceptions
v0.5.0 2026-01-02 Consolidated formatters, client cache, logging controls
v0.4.2 2025-12-08 Modular schema explorer, unified client/logging controls
v0.4.1 2025-01-22 Better error handling, debug logging
v0.4.0 2025-01-22 Added 6 schema discovery tools
v0.3.0 2025-01-17 SQL analysis engine
v0.2.0 2025-01-16 Basic validation & dry-run

🤝 Contributing

Pull requests are welcome! See our Contributing Guide.

# Setup development environment
git clone https://github.com/caron14/mcp-bigquery.git
cd mcp-bigquery
pip install -e ".[dev]"

# Run tests
pytest tests/

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

  • Google BigQuery team for the excellent API
  • Anthropic for the MCP protocol
  • All contributors and users

Built for safe BigQuery exploration 🛡️

Report Bug · Request Feature · Discussions

Metadata

Release files for mcp-bigquery 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-bigquery 0.7.0
File Size Uploaded Provenance Actions
mcp_bigquery-0.7.0.tar.gz 25.5 kB Without provenance Details for mcp_bigquery-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-bigquery 0.7.0
File Interpreter ABI Platform Actions
mcp_bigquery-0.7.0-py3-none-any.whl Python 3 none any Details for mcp_bigquery-0.7.0-py3-none-any.whl

Total release size: 58.4 kB

Release files / mcp_bigquery-0.7.0.tar.gz

Download URL mcp_bigquery-0.7.0.tar.gz
Size 25.5 kB
Tags Source
SHA-256 checksum
How to use checksums
63d969830777146d05984c5761471fda0a2e203ea27e285be0670574fe168e34
BLAKE2b-256 checksum
How to use checksums
e228315cc24dc8e5a069f9fe0e8697643fb5257c8911e60a3271ec3aa366a2fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.11

Release files / mcp_bigquery-0.7.0-py3-none-any.whl

Download URL mcp_bigquery-0.7.0-py3-none-any.whl
Size 32.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d297358aeb047d97f826df8e86de39eb510b90bb4c96ccdd8972fc1d5a3f4eb2
BLAKE2b-256 checksum
How to use checksums
c52e83b7a1dcc9e7a3060f5c9bdae044e765ef14ae3eab1ecb73b0b6f2ca9aef
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.11.11

Security for mcp-bigquery 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page