🗂️ BigQuery MCP Server

Practical MCP server for navigating BigQuery datasets and tables by LLMs. Designed for larger projects with many datasets/tables, optimized to keep LLM context small while staying fast and safe.

• Minimal by default: list datasets and tables names; fetch details only when asked
• Navigate larger projects: filter by name, request detailed metadata/schemas on demand
• Quick table insight: optional schema, column descriptions and fill-rate to help an agent decide relevance fast
• Safe to run: read-only query execution with guardrails (SELECT/WITH only, comment stripping)
• Supports vector search: Use bigquery as your vector store. See Vector Search section for full setup instructions.

Quick Start

Prerequisites: Python 3.10+ and uv package manager

🚀 Quick Setup

Option 1: Direct from PyPI (Recommended)

# 1. Authenticate
gcloud auth application-default login

# 2. Run server
uvx bigquery-mcp --project YOUR_PROJECT --location US

Option 2: Clone locally (development setup)

# 1. Clone and setup
git clone https://github.com/pvoo/bigquery-mcp.git
cd bigquery-mcp

# 2. Configure environment
cp .env.example .env
# Edit .env with your project and location

# 3. Run or inspect
make run      # Start server
make inspect  # Open MCP inspector

🔧 MCP Client Configuration

Option 1: PyPI package (Recommended) Simplest setup using the published PyPI package:

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "bigquery-mcp",
        "--project", "your-project-id",
        "--location", "US"
     ]
    }
  }
}

Option 2: Local clone (for development)

# Clone first
git clone https://github.com/pvoo/bigquery-mcp.git

{
  "mcpServers": {
    "bigquery": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/bigquery-mcp", "run", "bigquery-mcp"],
      "env": {
        "GCP_PROJECT_ID": "your-project-id",
        "BIGQUERY_LOCATION": "US"
      }
    }
  }
}

🧪 Test Your Setup

# Test with MCP inspector
npx @modelcontextprotocol/inspector uvx bigquery-mcp --project YOUR_PROJECT --location US

🔧 Configuration Options

All configuration can be set via CLI arguments or environment variables. CLI arguments take precedence.

Required Parameters

--project YOUR_PROJECT    # Google Cloud project ID
--location US             # BigQuery location (US, EU, etc.)

Optional Parameters

# Dataset Access Control
--datasets dataset1 dataset2    # Restrict to specific datasets (default: all datasets)

# Query & Result Limits
--list-max-results 500          # Max results for basic list operations (default: 500)
--detailed-list-max 25          # Max results for detailed list operations (default: 25)
--max-bytes-billed 109951162777  # Max bytes billed per query job (~USD 0.50/query)

# Table Analysis
--sample-rows 3                 # Sample data rows returned in get_table (default: 3)
--stats-sample-size 500         # Rows sampled for column fill rate calculations (default: 500)

# Authentication
--key-file /path/to/key.json    # Service account key file (default: ADC)