Thanassis Koukoutselos

Intro

Just days after Google Cloud rebranded the GenAI Toolbox for Databases to the MCP Toolbox for Databases, an exciting new capability appeared: support for BigQuery as a data source.

This is a big deal.

Why? Because it immediately unlocks three powerful advantages:

1. BigQuery datasets are everywhere — from Google’s public datasets to private enterprise data, the ecosystem is rich and growing.
2. The Model Context Protocol (MCP) has emerged as the go-to standard for connecting GenAI clients to real backend tools and data.
3. By combining both, we can now connect GenAI clients that support MCP (like Claude) directly to BigQuery — and run live queries, interactively, in natural language.

Let’s walk through how to wire all this up — and get Claude querying BigQuery using the MCP toolbox.

After hours of trial and error, obscure errors, and a bit of CLI sorcery, I successfully configured Claude to work with the MCP Toolbox for querying BigQuery directly from Claude’s interface.

This post outlines the exact steps I followed, including key troubleshooting tips and configuration files. Hopefully, it saves you (or your future self) hours of confusion.The big issue was that i coudn’t find a proper example online for the scenario below:

1. running MCP Toolbox locally
2. connecting to BigQuery
3. using MCP Toolbox from Claude Desktop (the exact config needed)

Tools Involved

• Claude desktop app (Anthropic)
• mcp-toolbox executable
• BigQuery + service account credentials
• Windows 10/11
• PowerShell

---

Step 1: Setup Your BigQuery Credentials

First, create a service account in Google Cloud Console and download the JSON credentials file.

Then define it in the Claude configuration (see below) — this is what I ended up doing. Trying to setup a system environment variable or using the google cloud command line tools on my desktop, didn’t work for me, as Claude is not taking those in account when launching the MCP toolbox.

---

Step 2: Write Your tools.yaml File

In your mcp-toolbox directory (e.g. C:\projects\mcp-toolbox), create a tools.yaml file like this. Note that identation plays a crucial role and if you are not careful, errors will emerge.

sources: 
  my-bq-source:
    kind: bigquery
    project: evident-healer-380615

tools:
  search_release_notes_bq:
    kind: bigquery-sql
    source: my-bq-source
    statement: |
      SELECT
        product_name, description, published_at
      FROM
        `bigquery-public-data`.`google_cloud_release_notes`.`release_notes`
      WHERE
        DATE(published_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
      GROUP BY product_name, description, published_at
      ORDER BY published_at DESC
    description: |
      Use this tool to get recent Google Cloud release notes.

toolsets:
  my_bq_toolset:
    - search_release_notes_bq

---

Step 3: Update claude_desktop_config.json

Claude uses this config to launch MCP servers. On Windows, this file is located at:

shellCopyEdit%AppData%\AnthropicClaude\claude_desktop_config.json

Here’s the working configuration I used:

{
  "mcpServers": {
    "bigquery-mcp-toolbox": {
      "command": "C:/projects/mcp-toolbox/toolbox.exe",
      "args": [
        "--tools-file", "C:/projects/mcp-toolbox/tools.yaml",
        "--stdio"
      ],
      "env": {
        "BIGQUERY_PROJECT": "your_project_id_here",
        "GOOGLE_APPLICATION_CREDENTIALS": "C:/projects/claude-bq/your_credentials_file_here.json"
      }
    }
  }
}

⚠️ Make sure to use forward slashes (/) even on Windows paths.

---

Step 4: Launch Claude and Use Your Tool

1. Open Claude normally
2. Go to the “Tools” tab or use the @tool keyword in chat.
3. Try invoking your tool by asking something like: @search_release_notes_bq Show me new GCP features

---

Common Pitfalls (and Fixes)

• ❌ Missing --stdio flag: Without it, Claude can’t talk to the tool.
• ❌ Wrong credential path: Backslashes (\) or typos will cause silent failures.
• ❌ Missing env block in claude_desktop_config.json: Your service account won’t be picked up unless GOOGLE_APPLICATION_CREDENTIALS is passed explicitly.
• ❌ Wrong JSON syntax: Use a JSON linter to validate claude_desktop_config.json.

---

✅ Success!

Once everything clicked into place, Claude started launching the BigQuery MCP toolbox without errors, and I could run SQL queries against BigQuery data from within the Claude chat window.

Here is an example of the result of a prompt such as

“can you plot the monthly revenue of my ecommerce store using bigquery data”?

---

📌 Final Thoughts

MCP is powerful but still evolving. Documentation is sparse, especially for Windows setups — so if you’re going down this path, be ready to debug. Hopefully, this post gets you much closer to the finish line.

Feel free to reach out or comment if you hit snags!

Resources:

• https://cloud.google.com/bigquery/docs/pre-built-tools-with-mcp-toolbox#configure-your-mcp-client
• https://github.com/googleapis/genai-toolbox
• https://medium.com/google-cloud/tutorial-mcp-toolbox-for-databases-exposing-big-query-datasets-9321f0064f4e
• https://codelabs.developers.google.com/mcp-toolbox-bigquery-dataset#0