BigQuery-Read-Only-MCP-Server

A production-readyBigQuery MCP serveryou deploy to your own GCP project. AI agents connect over HTTPS and can do exactly two things: read the schemas of tables you explicitly allowlist, and runSELECTqueries against them — subject to a configurable scan budget, a result-row cap, and a token-bucket rate limit. Nothing else. NoDROP, noINSERT, no schema discovery beyond what you allow, no surprise billing.

It exists because the alternatives — including Google's official BigQuery MCP server — exposeeverytable that the underlying service account can reach. That's the right default for trusted internal analysts. It's the wrong default for an autonomous agent that might be invoked by a customer-facing chatbot, a third-party tool, or a prompt-injected document.

You: Give me the highest-converting campaign in the last 30 days
LLM:queries your data and returns the result

Connect once, query everything. Point it at your Google Analytics 4 export, or import Google Ads, Meta, and TikTok into BigQuery to analyze every campaign across every channel from a single agent.

🏆 Why pick this over Google's official BigQuery MCP server

Hard table allowlist enforced in code, not just IAM.You list(dataset, table)pairs in env vars. Anything outside the allowlist is rejected at the SQL parser before a job is ever submitted — including qualified references likewrong_dataset.allowed_table. Google's server lets the agent see every table the SA's IAM permits.

Built-in rate limiting with token-bucket + burst.Google's docs are explicit:"The BigQuery MCP server doesn't have its own quotas. There is no limit on the number of calls that can be made to the MCP server."This server ships with configurableRATE_LIMIT_QPMandRATE_LIMIT_BURSTout of the box, plus separate concurrency semaphores for queries vs. metadata calls.

Read-only enforced by SQL parser, not just by IAM.DDL, DML, scripting, multi-statement bodies, and procedural constructs are rejected at the application layer in addition to whatever IAM gives you. Defense in depth — a misconfigured IAM grant can't accidentally enable writes.

Result-row cap (MAX_RESULT_ROWS).A query returning a million rows gets truncated server-side before it ever touches an LLM context window. Saves tokens, saves money, prevents accidental PII exfiltration through wide scans.

Dry-run cache.Repeated dry-runs of the same SQL hit an LRU + TTL cache, so an agent that retries or iterates doesn't generate redundant BigQuery API calls. Schema lookups are similarly cached with TTL.

Predictable, near-zero idle cost.Cloud Run scales to zero. You pay roughly nothing at idle and a few dollars per month under modest load. Compare to a managed endpoint where you're tied to whatever pricing model the vendor lands on post-GA.

Multi-tenant via env vars, no config file.Comma-separatedBQ_DATASET_IDandBQ_ALLOWED_TABLEpair positionally —analytics.events,reporting.daily, etc. Add or remove tables with a singlegcloud run deploy --update-env-vars. No config file to bake into the image, no redeploys of a separate config service.

Tiny tool surface.Only two tools exposed:get_table_schemaandquery_assessments. Smaller attack surface, easier to audit, less for the agent to misuse. Google's server exposes a genericexecute_sqlplus metadata-discovery tools that walk the full project graph.

One file, MIT licensed, ~1400 lines.Read the source. Fork it. Add a custom validator. Swap the auth scheme. You can't do any of that with a managed closed-source server.

When to pick Google's server instead:if you want forecasting and ARIMA out of the box, if you need Model Armor for prompt-injection scanning, or if you're comfortable letting the agent see everything the SA's IAM reaches and you don't need a hard scan ceiling.

When to pick this server:anything else — especially production agents, customer-facing deployments, regulated environments, multi-tenant scenarios, and anywhere the words "scan budget" or "rate limit" matter.

┌─────────────┐ HTTPS + X-API-KEY ┌──────────────────────┐ IAM ┌───────────┐ │ MCP client │ ────────────────────────────▶ │ Cloud Run service │ ─────────────────▶ │ BigQuery │ │ (Claude / │ API KEY │ bigquery-readonly- │ service account │ datasets │ │ Cursor / │ │ mcp-server │ │ + tables │ │ ChatGPT) │ │ │ │ │ └─────────────┘ │ • SQL allowlist │ └───────────┘ │ • Dry-run scan cap │ │ • Rate limiter │ ┌───────────┐ │ • Schema cache │ ◀───── secrets ── │ Secret │ └──────────────────────┘ │ Manager │ └───────────┘

gcloud services enable \ run.googleapis.com \ bigquery.googleapis.com \ secretmanager.googleapis.com \ artifactregistry.googleapis.com \ iam.googleapis.com \ cloudbuild.googleapis.com

🔐 Service account permissions (least privilege)

Create a dedicated service account —do notreuse one. The service needs the absolute minimum: read access to specific BigQuery tables, the ability to run query jobs, and read access to two secrets.

PROJECT_ID="your-project" SA_NAME="bigquery-readonly-mcp" SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" gcloud iam service-accounts create $SA_NAME \ --display-name="BigQuery Read-Only MCP Server"

gcloud projects add-iam-policy-binding $PROJECT_ID \ --member="serviceAccount:${SA_EMAIL}" \ --role="roles/bigquery.jobUser"

Grantbigquery.dataVieweron the specific dataset (preferred over project-wide)

# For each dataset in BQ_DATASET_ID: DATASET="your_dataset" bq add-iam-policy-binding \ --member="serviceAccount:${SA_EMAIL}" \ --role="roles/bigquery.dataViewer" \ "${PROJECT_ID}:${DATASET}"

For tighter control, grant access at thetablelevel instead of the dataset:

DATASET="your_dataset" TABLE="your_table" bq add-iam-policy-binding \ --member="serviceAccount:${SA_EMAIL}" \ --role="roles/bigquery.dataViewer" \ "${PROJECT_ID}:${DATASET}.${TABLE}"

gcloud secrets add-iam-policy-binding mcp-api-key \ --member="serviceAccount:${SA_EMAIL}" \ --role="roles/secretmanager.secretAccessor" gcloud secrets add-iam-policy-binding mcp-admin-key \ --member="serviceAccount:${SA_EMAIL}" \ --role="roles/secretmanager.secretAccessor"

That's the entire IAM footprint. Donotgrantbigquery.user,bigquery.admin,editor, orowner— none of those are needed and all of them grant strictly more than necessary.

# MCP API key (clients use this in X-API-KEY) openssl rand -hex 32 | gcloud secrets create mcp-api-key --data-file=- # Admin key (for the /admin endpoint — schema cache invalidation) openssl rand -hex 32 | gcloud secrets create mcp-admin-key --data-file=-

REGION="europe-north2" PROJECT_ID="your-project" REPO="bigquery-readonly-mcp" IMAGE="${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO}/server:latest" gcloud artifacts repositories create $REPO \ --repository-format=docker \ --location=$REGION gcloud builds submit --tag $IMAGE

gcloud run deploy bigquery-readonly-mcp \ --image="$IMAGE" \ --region="$REGION" \ --service-account="bigquery-readonly-mcp@${PROJECT_ID}.iam.gserviceaccount.com" \ --set-secrets="MCP_API_KEY=mcp-api-key:latest,MCP_ADMIN_KEY=mcp-admin-key:latest" \ --set-env-vars="\ GCP_PROJECT_ID=${PROJECT_ID},\ BQ_DATASET_ID=your_dataset,\ BQ_ALLOWED_TABLE=your_table,\ MAX_SCAN_MB=100,\ MAX_RESULT_ROWS=2000,\ BQ_JOB_TIMEOUT_SECS=60,\ MAX_SQL_LENGTH=2000,\ SCHEMA_TTL_SECS=300,\ DRY_RUN_CACHE_TTL_SECS=60,\ DRY_RUN_CACHE_MAX_ENTRIES=1000,\ RATE_LIMIT_QPM=20,\ RATE_LIMIT_BURST=5,\ QUERY_CONCURRENCY=10,\ META_CONCURRENCY=3,\ ADMIN_RATE_LIMIT_QPM=10,\ MAX_REQUEST_BODY_BYTES=65536" \ --allow-unauthenticated \ --port 8080

Formultiple datasets/tables, gcloud needs an alternate delimiter so commas inside values aren't split as separate vars:

gcloud run deploy bigquery-readonly-mcp \ --image="$IMAGE" \ ... --set-env-vars="^@^\ GCP_PROJECT_ID=${PROJECT_ID}@\ BQ_DATASET_ID=analytics,reporting,raw@\ BQ_ALLOWED_TABLE=events,daily_summary,events@\ MAX_SCAN_MB=100"

Datasets and tables are pairedpositionally: index 0 pairs with index 0. The example above allowsanalytics.events,reporting.daily_summary, andraw.events. List lengths must match.