BigQuery MCP Toolbox Setup

The MCP Toolbox for Databases is Google’s open-source (Apache 2.0) option for connecting AI assistants to BigQuery. Unlike the Remote MCP Server, you run it yourself — as a local binary, via NPX, or deployed to your own infrastructure. The tradeoff: more setup in exchange for more tools, better authentication, multi-database support, and support for custom parameterized queries.

For Claude Code users, the Toolbox is the practical choice: it uses Application Default Credentials (ADC) instead of manually refreshed tokens. As of v0.22.0, the Toolbox is still in beta.

What It Provides Beyond the Remote Server

The Remote Server gives you five basic tools. The Toolbox adds:

• bigquery-forecast — time series forecasting via BigQuery ML
• bigquery-conversational-analytics — natural language analytics
• bigquery-search-catalog — Data Catalog integration for discovering datasets
• bigquery-sql — execute pre-defined parameterized queries

The bigquery-sql tool is the most relevant for data teams: it provides structured access to data without allowing arbitrary SQL, which is safer for production use.

Installation

macOS (Apple Silicon):

export VERSION=0.22.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/arm64/toolbox
chmod +x toolbox

macOS (Intel):

export VERSION=0.22.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/darwin/amd64/toolbox
chmod +x toolbox

Linux (AMD64):

export VERSION=0.22.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Via Homebrew:

brew install mcp-toolbox

Via NPX (no local install):

npx -y @toolbox-sdk/server --prebuilt bigquery --stdio

NPX adds startup latency. For regular use, download the binary.

Authentication

The Toolbox uses Application Default Credentials (ADC). This is the most common stumbling block in the setup — ADC is a separate credential from your regular gcloud auth login. See the dedicated note on GCP Application Default Credentials for the full explanation.

The short version: run both commands:

# Your regular gcloud CLI auth (you probably already have this)
gcloud auth login

# ADC -- what the Toolbox actually uses
gcloud auth application-default login

The second command opens a browser for OAuth consent. Credentials land at ~/.config/gcloud/application_default_credentials.json.

For production, use a service account key:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

Set your project:

export BIGQUERY_PROJECT="your-project-id"

Then start the server:

./toolbox --prebuilt bigquery --stdio

The --stdio flag runs in stdio mode, which is what MCP clients like Claude Desktop expect. This maps to the stdio transport described in MCP Protocol Architecture.

Critical: after updating credentials, you must restart Claude Code or Claude Desktop. The MCP server reads credentials at startup and does not detect changes while running. With Claude Code, you may need to restart twice — once for the new config, once for the credentials.

Claude Desktop Configuration

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/yourname/tools/toolbox",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "your-project-id"
      }
    }
  }
}

Replace the command path with wherever you installed the binary.

For the NPX variant:

{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": ["-y", "@toolbox-sdk/server", "--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "your-project-id"
      }
    }
  }
}

Claude Code Configuration

The fastest path:

claude mcp add bigquery -- npx -y @toolbox-sdk/server --prebuilt bigquery --stdio

Then add the environment variable:

claude mcp edit bigquery

Add BIGQUERY_PROJECT in the editor that opens.

For team projects, use a project-scoped configuration that you can commit:

claude mcp add bigquery -s project -- npx -y @toolbox-sdk/server --prebuilt bigquery --stdio

This creates a .mcp.json file in your project root. Teammates clone the repo and get the same MCP configuration automatically — no manual setup per developer.

Troubleshooting

Silent failures on list operations

When permissions are missing, list_dataset_ids and similar tools may return empty results without any error. The execute_sql tool gives clear 403 errors, but list operations fail silently.

If you get empty results when you expect data:

1. Verify ADC is set up: gcloud auth application-default print-access-token should return a token
2. Check the project: echo $BIGQUERY_PROJECT should show your project ID
3. Test with execute_sql instead — it gives clearer error messages

Authentication errors after gcloud auth login

If gcloud auth login works but the Toolbox gives permission errors, you need ADC:

gcloud auth application-default login

Then restart your MCP client.

Credentials not picked up after changes

The MCP server reads credentials once at startup. Update credentials, then restart the application. This is the single most common “why isn’t it working” question, and the answer is always “did you restart?”