Skip to content

Installation & Setup

Prerequisites

  • Python: 3.10 or higher
  • Google Cloud SDK: Required for authentication
  • BigQuery API: Must be enabled in your GCP project

Installation

pip install mcp-bigquery

Or with uv: 

uv pip install mcp-bigquery

From Source

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

Verify Installation

# Check version
mcp-bigquery --version

# Test server start
python -m mcp_bigquery

Authentication

Quick Setup (Local Development)

# Login with your Google account
gcloud auth application-default login

# Set default project
gcloud config set project YOUR_PROJECT_ID

# Verify authentication
gcloud auth application-default print-access-token

Service Account (Production)

# Create service account
gcloud iam service-accounts create mcp-bigquery \
  --display-name="MCP BigQuery Service Account"

# Grant permissions
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:mcp-bigquery@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/bigquery.jobUser"

# Generate key file
gcloud iam service-accounts keys create key.json \
  --iam-account="mcp-bigquery@YOUR_PROJECT_ID.iam.gserviceaccount.com"

# Use the key
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Required Permissions

MCP BigQuery needs these IAM roles: - roles/bigquery.jobUser - Create and run dry-run jobs - roles/bigquery.dataViewer - Access table metadata

Configuration

Environment Variables

# Google Cloud Project (optional, uses default from gcloud)
export BQ_PROJECT="your-project-id"

# BigQuery Location (optional)
export BQ_LOCATION="US"  # or EU, asia-northeast1, etc.

# Cost estimation price per TiB (optional, default: 5.0)
export SAFE_PRICE_PER_TIB="5.0"

# Service account key (optional)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Claude Code Configuration

Add to your Claude Code configuration file:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "mcp-bigquery",
      "env": {
        "BQ_PROJECT": "your-project-id",
        "BQ_LOCATION": "US",
        "SAFE_PRICE_PER_TIB": "5.0"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "mcp-bigquery": {
      "command": "python",
      "args": ["-m", "mcp_bigquery"],
      "env": {
        "BQ_PROJECT": "your-project-id"
      }
    }
  }
}

Quick Start

Your First Validation

Validate a simple SQL query:

{
  "tool": "bq_validate_sql",
  "arguments": {
    "sql": "SELECT 1 as test_column"
  }
}

Response: 

{
  "isValid": true
}

Check Query Cost

Estimate cost using a public dataset:

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

Response: 

{
  "totalBytesProcessed": 65536,
  "usdEstimate": 0.00032,
  "referencedTables": [{
    "project": "bigquery-public-data",
    "dataset": "samples",
    "table": "shakespeare"
  }],
  "schemaPreview": [
    {"name": "word", "type": "STRING", "mode": "NULLABLE"},
    {"name": "word_count", "type": "INT64", "mode": "NULLABLE"}
  ]
}

Using Parameters

{
  "tool": "bq_validate_sql",
  "arguments": {
    "sql": "SELECT * FROM users WHERE created_date = @date",
    "params": {
      "date": "2024-01-01"
    }
  }
}

Troubleshooting

Authentication Errors

"Could not automatically determine credentials" 

gcloud auth application-default login

"Permission denied" 

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

Common Issues

Command 'mcp-bigquery' not found 

# Use Python module instead
python -m mcp_bigquery

Project not found 

export BQ_PROJECT="your-project-id"

BigQuery API not enabled 

gcloud services enable bigquery.googleapis.com --project=YOUR_PROJECT

Security Best Practices

  1. Never commit credentials - Use environment variables or secret managers
  2. Use service accounts - Create dedicated accounts with minimal permissions
  3. Rotate keys regularly - Set up key rotation policies
  4. Enable audit logging - Track all BigQuery operations

Next Steps