mcp-bigquery

Safe BigQuery exploration through Model Context Protocol

Documentation | Quick Start | Examples

Overview

mcp-bigquery is a Model Context Protocol (MCP) server that enables AI assistants (such as Claude) to interact securely with Google BigQuery.

Key Features

• Secure execution: All operations are strictly limited to dry-run verification. The server never executes queries that mutate data or incur execution costs.
• Cost transparency: Provides estimates of query costs and processed bytes before execution.
• Static analysis: Analyzes query dependencies and validates SQL syntax.
• Schema exploration: Browses datasets, tables, and columns.

Business Value

Quick Start

Step 1: Installation

Install the package via pip:

pip install mcp-bigquery

Step 2: Authentication

Set up Google Cloud Platform authentication:

# For user account authentication
gcloud auth application-default login

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

Step 3: Claude Desktop Configuration

Configure the server in the Claude Desktop configuration file:

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

Add the following entry:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "your-gcp-project-id"
      }
    }
  }
}

Step 4: Verification

Restart Claude Desktop and run the following queries to verify the setup:

• "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 and Analysis

Schema Discovery

[!IMPORTANT] The bq_preview_table tool uses client.list_rows (API: tabledata.list) to retrieve sample rows directly, resulting in zero bytes scanned and no execution costs. To prevent unintended exposure of sensitive information (such as PII) to the LLM, this tool is disabled by default. You must explicitly opt in by setting MCP_BQ_ENABLE_PREVIEW=true in your environment config.

Configuration

Environment Variables

Example .env File

For local testing or development environments, you can define these variables in a .env file:

BQ_PROJECT=your-gcp-project-id
BQ_LOCATION=asia-northeast1
SAFE_PRICE_PER_TIB=5.0
LOG_LEVEL=WARNING
MCP_BQ_ENABLE_PREVIEW=true

Complete Claude Desktop Configuration Example

{
  "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

Mapped Errors and Solutions

Authentication Error

Error: Could not automatically determine credentials

• Solution: Re-authenticate using the command line:

  gcloud auth application-default login
  

Permission Denied

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

• Solution: Grant the BigQuery Data Viewer role to the target identity:

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

Project ID Missing

Error: Project ID is required

• Solution: Ensure the BQ_PROJECT variable is set correctly in your configuration.

Examples of Usage

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

Project Status and Version History

Development and Contribution

For instructions on local development setup and contribution policies, please refer to the CONTRIBUTING.md guide.

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

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

# Execute the test suite
pytest tests/

License

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