BigQuery-MCP GitHub Distribution V1

Company distribution for a read-only Google BigQuery MCP server, built on the official Google MCP Toolbox for Databases v1.8.0. V1 production support is macOS on Apple Silicon. The installer is deliberately fail-closed on other platforms, even where the release manifest records an official checksum.

The installed server exposes exactly these stable tool names: find_*, color_*, paintbynumber_*, and pixelspark_* (list tables, table metadata, and SQL for each group). Every generated source is dataset-scoped with writeMode: blocked, a 200-row result cap, and 10 GiB maximum billed bytes. SQL use is read-only: use SELECT only.

Install

Prerequisites: Node.js 20+ and Google Cloud CLI. Authentication uses your existing Google Application Default Credentials (ADC); no credential, token, project ID, or dataset ID is committed by this package.

1. Copy and fill the local configuration. Do not commit it.

   cp config.example.json config.local.json

2. If ADC is not already set up, authenticate interactively (the installer never runs this):

   gcloud auth application-default login

3. Install the pinned binary and generated local configuration:

   node install.js --config config.local.json

The default install root is ~/Library/Application Support/BigQuery-MCP. The command prints a structured receipt and copyable Codex/Cursor stdio snippets; it never edits either client configuration. For a no-network, locally verified install (useful for tests), add --toolbox-source /path/to/toolbox.

Related MCP server: BigQuery MCP Server

Client configuration

The installer prints two separate, copyable client snippets:

• clientConfig.codexToml: TOML for Codex ~/.codex/config.toml.

• clientConfig.cursorJson: JSON object for Cursor MCP configuration.

Both point at the installed binary with:

--stdio --config <installed config path> --disable-reload

The installer only prints these snippets; it never edits an existing Codex or Cursor configuration.

Verify

node status.js
node smoke-test.js

The default smoke test starts the local MCP stdio server and requires exactly the expected 12 tools; it makes no MCP tools/call request. Toolbox v1.8.0 itself validates configured allowedDatasets during source initialization, so a successful stdio start may require ADC and network access even in this default mode. A deliberately opt-in read-only live check requires a real table identifier:

node smoke-test.js --live --group find --table events_YYYYMMDD

The live check performs only list_table_ids, SELECT 1 AS smoke_test, and get_table_info. It does not write data, authenticate, or inspect credential files.

Versioning and upgrades

V1 is pinned to Toolbox 1.8.0; the downloader never uses latest. The known release URLs and SHA-256 values are in release-manifest.json. Upgrade work is intentionally separate: update the manifest, validate the release independently, then publish a new distribution revision. Do not replace the pin casually.

Repository boundaries

This working directory also contains machine-local production assets that predate the distribution package. They are deliberately kept on disk but ignored by Git:

• toolbox — the existing ~154 MB production binary.

• toolbox.yaml and tools_bootstrap.yaml — current machine production configuration containing real project/dataset identifiers.

• BigQuery_MCP_正式配置与恢复说明_20260816.md — local historical recovery notes.

• config.local.json, runtime/state/log/cache material, and credential-like files.

The tracked distribution source should therefore contain the installer, generator, manifest, example config, tests, smoke/status tools, README, and .gitignore only. Do not force-add ignored production assets.