BigQuery MCP Server

A standalone MCP server that connects Claude Desktop to BigQuery. Ask questions in plain English — Claude writes and runs the SQL for you.

How it works

Claude Desktop launches this server as a local process on startup. It exposes three tools:

• bigquery_get_schema — returns all table schemas plus pre-loaded sample rows so Claude understands your data before writing any SQL
• bigquery_execute_query — runs a SQL SELECT and returns results as JSON (capped at 500 rows)
• bigquery_refresh_samples — fetches sample rows from all tables using TABLESAMPLE and caches them to disk

Prerequisites

• Node.js 20+
• Google Cloud CLI
• Claude Desktop

Setup

Step 1: Authenticate with Google Cloud

This step is interactive and must be done manually regardless of which setup method you choose:

gcloud auth application-default login

Step 2: Clone the repo

git clone https://github.com/prakhargarg105/bq_mcp.git
cd bq_mcp

Step 3: Install, build, and configure

Option A — Let Claude Code handle it (recommended)

Open Claude Code in the repo:

claude

Then paste this prompt:

Install dependencies, build the MCP server, and register it with Claude Desktop.

Steps:
1. Run `npm install` in the repo root
2. Run `npm install && npm run build` inside the `mcp-server/` directory
3. Open ~/Library/Application Support/Claude/claude_desktop_config.json (create it if it doesn't exist) and add this bigquery entry inside the mcpServers block, preserving any existing entries:
   {
     "command": "node",
     "args": ["<absolute path to this repo>/mcp-server/dist/index.js"],
     "env": {
       "BIGQUERY_PROJECT_ID": "vectorized",
       "BIGQUERY_REGION": "us",
       "BIGQUERY_DATASETS": "callhome_base,callhome_layer_1,callhome_layer_2,callhome_layer_3,silver_usage,salesforce_layer_1,salesforce_layer_2,salesforce_layer_3"
     }
   }
   Use the actual absolute path of this repo for the args value.
4. Confirm what was written to the config file.

Option B — Manual

# Install root dependencies
npm install

# Install and build the MCP server
cd mcp-server
npm install
npm run build
cd ..

Then open (or create) ~/Library/Application Support/Claude/claude_desktop_config.json and add the following inside the mcpServers block:

{
  "mcpServers": {
    "bigquery": {
      "command": "node",
      "args": ["/absolute/path/to/bq_mcp/mcp-server/dist/index.js"],
      "env": {
        "BIGQUERY_PROJECT_ID": "vectorized",
        "BIGQUERY_REGION": "us",
        "BIGQUERY_DATASETS": "callhome_base,callhome_layer_1,callhome_layer_2,callhome_layer_3,silver_usage,salesforce_layer_1,salesforce_layer_2,salesforce_layer_3"
      }
    }
  }
}

Replace /absolute/path/to/bq_mcp with the actual path where you cloned this repo.

Step 4: Restart Claude Desktop

Quit completely (Cmd+Q on Mac) and reopen.

Step 5: Load sample rows

In a new Claude Desktop conversation, say:

"Please refresh my BigQuery samples"

Claude will call bigquery_refresh_samples, which fetches a small sample from each table and caches it to disk. This only needs to be done once, or when your data changes significantly.

Step 6: Start querying

Ask Claude anything about your data:

"What were the top 10 customers by revenue last month?" "Show me a breakdown of signups by month for this year" "Which datasets do I have access to?"

Claude will call bigquery_get_schema to understand your tables, then bigquery_execute_query to run the SQL and return results.

Environment variables

Variable	Required	Description
BIGQUERY_PROJECT_ID	Yes	GCP project ID — always vectorized
BIGQUERY_REGION	Yes	BigQuery region — always us
BIGQUERY_DATASETS	Recommended	Comma-separated list of datasets to include. If omitted, all datasets are included which may exceed Claude's context limit.
GOOGLE_APPLICATION_CREDENTIALS	No	Path to a service account key JSON. If omitted, Application Default Credentials are used (recommended).