Skip to main content

​
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.
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

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

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.
All queries are billed to the project ID you provide — including queries against public datasets like bigquery-public-data.
3

Add to Civic

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

Authorize

On first use, you will be redirected to Google to authorize the connection.
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 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 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 all tables in a dataset. Returns {} when the dataset is empty.
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 — 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.
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.
Configure guardrails via the Civic UI or ask the Configurator Agent: “Add guardrails to my BigQuery server.”