AI Knowledge Hub
Menu

Tools & MCP / Warehouse

BigQuery MCP Query Runner

Launchable read-only BigQuery MCP server with parameter binding, scope isolation, dry-run cost enforcement, bounded pagination, and typed diagnostics.

Access

Read only · Google BigQuery

Setup requiredAPI or MCP integrationRequirements & limitsRelated reading

Inputs

The released example shows these fields. Check the guide for which are required.

  • query
  • parameters
  • project_id
  • billing_project_id
  • location
  • max_rows
  • page_size
  • timeout_ms

Outputs

The released example shows these fields. Check the guide for which are required.

  • schema_version
  • project_id
  • billing_project_id
  • location
  • schema
  • rows
  • pagination
  • diagnostics
  • source

Before you begin

  • Node.js 22 or newer.
  • BQ_CREDENTIAL and a BQ_POLICY envelope defining project, billing project, dataset, location, byte, row, timeout, and user-OAuth authority.
  • Google BigQuery API enabled with least-privilege access to the configured datasets.

Try this first

Review the setup requirements, access boundaries and release guide before connected use.

Limits for this step
  • Only SELECT or WITH GoogleSQL is accepted; scripts, DML, DDL, external queries, destinations, and unqualified external tables are rejected.
  • Workload identity uses Google STS plus service-account impersonation; direct unidentifiable federated tokens are not accepted for readiness evidence.
  • Provider verification requires a clean-client sandbox smoke observation; deterministic tests do not satisfy that release evidence gate.
  • Read-only queries only; project, billing project, dataset, location, SQL, parameter, byte, row, page, timeout, and response-size restrictions are enforced before results are returned.
Review setup requirements

Summary sources · Catalogue metadata, tool.yaml, TOOL.md, examples/input.json, examples/output.json · v0.2.0 · Release package

View capabilities and accessHide capabilities and accessv0.2.0

What it can do

  • Execute one parameterized read-only GoogleSQL query inside configured project, dataset, and location boundaries.
  • Dry-run every query and enforce provider-side maximum bytes billed before execution.
  • Return typed rows with bounded pagination, job identity, cost, cache, timeout, and source diagnostics.

Access limits

Read-only queries only; project, billing project, dataset, location, SQL, parameter, byte, row, page, timeout, and response-size restrictions are enforced before results are returned.

Trust boundary · remote-mcp-server

Credentials and setup

  • BigQuery OAuth credential with jobs.create and read access only to the configured datasets

Install tool files

These commands install package files and generate runtime configuration where supported. Confirm discovery in your agent app, then check configuration, authentication and a first useful operation.

Install (Codex)

./bin/skills-hub install --module tools --entry warehouse/[email protected] --runtime codex

Install (Claude)

./bin/skills-hub install --module tools --entry warehouse/[email protected] --runtime claude

Install (Generic)

./bin/skills-hub install --module tools --entry warehouse/[email protected] --runtime generic --target ./my-agent/tools-mcp

How You Can Use This

Setup required

Resource form: API or MCP integration

Configuration, credentials or runtime bindings are required. Check the prerequisites and limits for your intended environment.

First run: Configure BQ_CREDENTIAL and BQ_POLICY, then register .mcp.json with Codex, Claude, or a generic MCP client.

Setup required

  • Node.js 22 or newer.
  • BQ_CREDENTIAL and a BQ_POLICY envelope defining project, billing project, dataset, location, byte, row, timeout, and user-OAuth authority.
  • Google BigQuery API enabled with least-privilege access to the configured datasets.

Current limits

  • Only SELECT or WITH GoogleSQL is accepted; scripts, DML, DDL, external queries, destinations, and unqualified external tables are rejected.
  • Workload identity uses Google STS plus service-account impersonation; direct unidentifiable federated tokens are not accepted for readiness evidence.
  • Provider verification requires a clean-client sandbox smoke observation; deterministic tests do not satisfy that release evidence gate.
What installation and verification mean
File installation
Places package files and generated configuration in the selected directories.
Native discovery
Your agent app finds and accepts the instructions, tools or plugin registrations.
Mock execution
Exercises sample fixtures. Connected data and provider effects need a separate check.
Connected operation
Requires current configuration, provider authentication, scoped permissions and a successful operation in your intended environment.

Declared compatibility

Maintainer-reviewed information for version 0.2.0 · Reviewed 2026-10-31. This is not a live provider check.

  • Packaged API target: Google BigQuery API v2
  • Runtime: Node.js 22 or newer
  • Uses Node's built-in HTTP functionality; no Google SDK is packaged.

Limits

  • Requires BigQuery credentials and a policy defining allowed projects, datasets, locations and query budgets.
  • Accepts one read-only SELECT or WITH GoogleSQL query; scripts, DML and DDL are rejected.

Reviewed BigQuery release implementation

Classification: declared

Technical details and release files

Review and lifecycle

Review maturity: Experimental

Security review declaration: Not declared

Lifecycle: Active

These release declarations are separate from evidence that a workflow operates in your environment.

Runtime & Dependencies

ID: warehouse/bigquery-mcp-query-runner

Tags: bigquery, mcp, sql, read-only

Runtimes: codex, claude, generic

Dependencies & Setup

MCP servers: Not documented

APIs: Google BigQuery API v2, Google OAuth 2.0 and Security Token Service

Local tools: Not documented