Skip to main content

Google BigQuery

Overview​

The BigQuery MCP server provides read-only access to Google BigQuery — querying data with full SQL power and inspecting dataset/table metadata. It supports GoogleSQL SELECT queries, INFORMATION_SCHEMA views, dry-run cost estimation, and built-in AI.FORECAST for time-series forecasting.

info

Read-only — No DDL (CREATE/DROP/ALTER) or DML (INSERT/UPDATE/DELETE). Schema and data management must be done via the GCP Console, bq CLI, or Terraform.

How to Add BigQuery​

  1. 1
    Enable the BigQuery API
    1. Go to the Google Cloud Console
    2. Select your project (or create one)
    3. Navigate to APIs & Services → Library
    4. Search for BigQuery API and click Enable
  2. 2
    Check Permissions

    Your Google account must have at minimum roles/bigquery.dataViewer + roles/bigquery.jobUser on the project. Check this under IAM & Admin → IAM in the GCP Console.

    warning

    All queries are billed to the project ID you provide — including queries against public datasets like bigquery-public-data.

  3. 3
    Add to Civic

    Add the Google BigQuery server to your Civic environment through the server directory.

  4. 4
    Authorize

    On first use, you will be redirected to Google to authorize the connection.

  5. 5
    Test Connection

    Start with "What datasets exist in my BigQuery project?" to verify the connection.

What You Can Do​

SQL Queries

Run GoogleSQL SELECT queries with dry-run cost estimation and AI.FORECAST support

Schema Inspection

Browse datasets, tables, columns, types, and row counts

Access Auditing

View dataset ACLs — who has OWNER, WRITER, READER access

Cost Management

Validate queries with dry-run mode before incurring costs

Use Cases​

Data Exploration​

  • Project Inventory: "What datasets and tables do I have in my BigQuery project?"
  • Schema Discovery: "Show me the schema of the analytics.users table"
  • Access Audit: "Who has access to my analytics dataset?"

Querying​

  • Row Counts: "How many rows are in each table in my analytics dataset?"
  • Analysis: "Show me the top 10 most common names in the US between 1990 and 2013"
  • Joins: "Write a query to join users and events and show me each user's event count"
  • Forecasting: "Forecast the next 7 days of sales from my iowa_liquor_sales data"

Cost Control​

  • Dry Run: "Validate this query without running it: SELECT ..."
  • Job History: "Show me all jobs run in my project in the last 24 hours using INFORMATION_SCHEMA"

Available Tools (5)​

Metadata Inspection​

list_dataset_ids

list_dataset_ids — List all datasets in a project. Own-project only — returns 403 on external projects. Use INFORMATION_SCHEMA.SCHEMATA via execute_sql for cross-project metadata.

get_dataset_info

get_dataset_info — Get full metadata for a dataset including creation time, location, time-travel hours, and the full ACL (access control list with roles and user grants).

list_table_ids

list_table_ids — List all tables in a dataset. Returns {} when the dataset is empty.

get_table_info

get_table_info — Get full table metadata including schema (field names, types, modes), row count, storage size, table type (TABLE/VIEW/EXTERNAL/MATERIALIZED_VIEW), and timestamps.

Query Execution​

execute_sql

execute_sql — Run a GoogleSQL SELECT query against any accessible table. Supports dryRun: true to validate and estimate cost without executing. Also supports INFORMATION_SCHEMA queries and AI.FORECAST for time-series forecasting.

note

SELECT only — No DDL or DML operations.

Metadata tools are own-project only — list_dataset_ids, get_dataset_info, list_table_ids, and get_table_info return 403 on external projects. Use INFORMATION_SCHEMA via execute_sql instead.

Timestamps are epoch floats — All timestamps are returned as Unix epoch float strings (e.g. "1.7722368E9"), not ISO 8601. Use FORMAT_TIMESTAMP in your query for readable output.

Always use LIMIT — Unbounded queries on large tables produce huge responses and incur unnecessary cost. Use dryRun: true first for expensive queries.

Partition filtering — BigQuery tables are often partitioned by date. Filter on the partition column to dramatically reduce cost.

Guardrails​

This server supports all 14 universal guardrails. Server-specific guardrails are coming soon.

tip

Configure guardrails via the Civic UI or ask the Configurator Agent: "Add guardrails to my BigQuery server."