# MCP Toolbox for Databases (BigQuery): an MCP server we run in production

Canonical: https://scalably.io/mcp/mcp-toolbox-bigquery
Source: https://github.com/googleapis/mcp-toolbox
Registry: not published to the MCP registry
Provenance: third-party server, pinned at 1.8.0, verified 2026-10-02. Verification note: install uses --config (the v1.8.0 README flag; --tools-file still works but warns); env var BIGQUERY_PROJECT and the tool names come from the pinned prebuilt bigquery.yaml Newer upstream available: 1.13.1; the pin stays at 1.8.0 until it is re-verified.
Integrity: no independent hash is published for this third-party listing; the raw endpoint at https://scalably.io/mcp/mcp-toolbox-bigquery.md mirrors this representation byte for byte
This is the machine-readable representation of the page at the canonical URL. Same facts, denser format.

## Direct answer
BigQuery datasets, tables and SQL for reporting agents, through a tools.yaml config.

## Install
- Claude Code: `curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v1.8.0/darwin/arm64/toolbox && chmod +x toolbox && ./toolbox --config tools.yaml --stdio`
- Codex: not available for this server.
- Claude Desktop: not available for this server.

## Environment
| Variable | Required | Secret | Purpose |
|---|---|---|---|
| `BIGQUERY_PROJECT` | yes | no | GCP project ID |
| `GOOGLE_APPLICATION_CREDENTIALS` | no | no | service-account key path; one way to supply Application Default Credentials, which is how we run it |

## Tools
| Tool | Description |
|---|---|
| `analyze_contribution` | Contribution (key driver) analysis on a table. |
| `ask_data_insights` | Data analysis and answers to complex questions about the contents of specific tables. |
| `execute_sql` | Executes a SQL statement. |
| `forecast` | Forecasts time series data. |
| `get_dataset_info` | Gets dataset metadata. |
| `get_table_info` | Gets table metadata. |
| `list_dataset_ids` | Lists datasets. |
| `list_table_ids` | Lists tables. |
| `search_catalog` | Searches catalog entries for the given query. |

## Setup
- Install the binary for your OS from the project's GCS bucket (the install line above is macOS Apple Silicon), or `brew install mcp-toolbox`, or `npx @toolbox-sdk/server`.
- Run the prebuilt BigQuery config: `toolbox --prebuilt bigquery --stdio`. Pick a subset with `--prebuilt bigquery/data` (SQL and metadata) or `bigquery/analytics` (contribution analysis, insights, forecast).
- Required: `BIGQUERY_PROJECT`. Optional: `BIGQUERY_LOCATION`, `BIGQUERY_MAXIMUM_BYTES_BILLED`, `BIGQUERY_MAX_QUERY_RESULT_ROWS` (default 50), `BIGQUERY_USE_CLIENT_OAUTH`, `BIGQUERY_IMPERSONATE_SERVICE_ACCOUNT`.
- Auth is Application Default Credentials by default.


## Limits
- `execute_sql` can write: the source's `writeMode` defaults to allowed, and the prebuilt config has no variable to change it. Grant the service account read roles only if agents should not modify data.
- Roles: `roles/bigquery.user` and `roles/bigquery.metadataViewer`; `roles/bigquery.dataEditor` only to create or modify datasets and tables; `roles/cloudaicompanion.user` for `ask_data_insights`.
- Results are capped at 50 rows by default.
- Set `BIGQUERY_MAXIMUM_BYTES_BILLED`: queries over the limit fail before executing and cost nothing.

Sources: googleapis/mcp-toolbox v1.8.0 docs (integrations/bigquery prebuilt config and source pages) and `internal/prebuiltconfigs/tools/bigquery.yaml`.


## Reliability
- CI: not applicable, this is a third-party project we do not control.
- Pinned at 1.8.0 Newer upstream available: 1.13.1; the pin stays at 1.8.0 until it is re-verified.
- Verified 2026-10-02
- We run this server in production, pinned at the exact version, with the install command derived mechanically from that pin so it can be re-verified against the published package. install uses --config (the v1.8.0 README flag; --tools-file still works but warns); env var BIGQUERY_PROJECT and the tool names come from the pinned prebuilt bigquery.yaml

## Related
- Read more: [Claude Code MCP: how to add an MCP server](https://scalably.io/blog/claude-code-mcp), [What is an MCP server? A clear explainer for developers](https://scalably.io/blog/what-is-an-mcp-server)