GCP BigQuery MCP Server

May 9, 2026 · View on GitHub

GCP BigQuery MCP Server — Quick Start

Tutorial 5 of 7 | ⏱️ Time: 30-40 minutes | 💻 Level: Intermediate

Last Updated: May 2026

🎯 What You'll Learn

Set up Google's official MCP Toolbox for BigQuery billing exports
Create and configure a GCP service account with proper permissions
Install the Toolbox binary for Claude Desktop integration
Query GCP billing data at scale using natural language
Analyze multi-cloud cost comparisons and optimization insights

1. Overview

The GCP BigQuery MCP server (via Toolbox) allows you to query Google Cloud Billing Export data directly in Claude Desktop for FinOps use cases such as:

Cost analysis and reporting
Spend anomaly detection
Resource optimization insights
Multi-cloud cost comparisons

This tutorial walks you through setting up the BigQuery MCP server using the Toolbox binary with a dedicated GCP service account.

Choosing Between Official and Community GCP MCP Servers

There are two approaches to accessing GCP billing data through MCP servers:

Official MCP Server (This Tutorial): Uses Google's MCP Toolbox for Databases with the --prebuilt bigquery option. This is a production-ready, officially maintained solution that works with Claude Desktop and requires minimal setup. You install a single binary and configure it with your GCP credentials.

Community MCP Server: Uses the krzko/google-cloud-mcp community project, which requires building from source with Node.js and pnpm. This approach offers more customization options and works with multiple AI clients (VS Code, Google Gemini) but requires more setup steps.

Feature	Official (Toolbox)	Community (krzko)
Maintenance	Google-maintained	Community-maintained
Installation	Single binary download	Build from source (Node.js)
Setup Complexity	Low (3 steps)	Medium (5+ steps)
Production Ready	✅ Yes	⚠️ Beta
Claude Desktop	✅ Native support	✅ Supported
VS Code/Gemini	❌ Not applicable	✅ Supported
Customization	Pre-built tools	Full source access
Updates	Automatic with new releases	Manual rebuild required

Recommendation: Start with the official Toolbox approach (this tutorial) for production use with Claude Desktop. Consider the community server if you need multi-client support or want to customize the implementation.

2. Prerequisites

Before starting, ensure you have:

GCP Billing Export to BigQuery enabled (Setup Guide)
Claude Desktop installed (Installation Guide)
A GCP Service Account with appropriate permissions (see below)
Toolbox binary for your platform (provided or compiled from Google's official MCP Toolbox for Databases), set up is explained below after the Service Account set up.

3. Step 1: Create and Configure GCP Service Account

a. Create the Service Account

Go to GCP Console > IAM & Admin > Service Accounts
Select your project (e.g., gcp-mcp-server)
Click "+ CREATE SERVICE ACCOUNT"
Enter details:
- Name: gcp-mcp-dataviewer
- Description: Service account for MCP BigQuery cost analysis
Click "CREATE AND CONTINUE"

b. Grant Required Roles (Project Level)

On the "Grant this service account access to project" screen, add these roles:

BigQuery Data Viewer - Allows reading data from BigQuery datasets
BigQuery Job User - Allows running queries (recommended)

Note: Do NOT add "Viewer" or "Billing Account Viewer" here - these are either too broad or must be assigned at a different level.

Click "CONTINUE" then "DONE"

c. Grant Billing Account Viewer Role (Billing Account Level)

Important: This role must be assigned at the Billing Account level, not at the project level.

Go to GCP Console > Billing
Select your Billing Account (the one linked to your billing export)
Click "Account Management" in the left sidebar
Click "ADD PRINCIPAL" (or "ADD MEMBER")
In the "New principals" field, enter your service account email:
- Format: gcp-mcp-dataviewer@YOUR-PROJECT-ID.iam.gserviceaccount.com
- You can copy this from the Service Accounts page
In "Select a role", choose: Billing Account Viewer
Click "SAVE"

Why this role? The Billing Account Viewer role (roles/billing.viewer) allows the service account to access billing metadata and currency information required for comprehensive cost analysis.

d. Create and Download JSON Key

Return to GCP Console > IAM & Admin > Service Accounts
Find your newly created service account in the list
Click on it to open details
Go to the "KEYS" tab
Click "ADD KEY" > "Create new key"
Choose JSON format
Click "CREATE"
The key file downloads automatically (e.g., gcp-mcp-dataviewer.json)

e. Store the Key Securely

Create a secure directory for keys:

macOS/Linux:

mkdir -p ~/.config/gcloud/keys
mv ~/Downloads/gcp-mcp-dataviewer.json ~/.config/gcloud/keys/
chmod 600 ~/.config/gcloud/keys/*.json

Windows (PowerShell):

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\Documents\keys"
Move-Item "$env:USERPROFILE\Downloads\gcp-mcp-dataviewer.json" "$env:USERPROFILE\Documents\keys\"

⚠️ Important: Never commit service account keys to Git repositories!

4. Step 2: Install Toolbox Binary

The Toolbox binary provides MCP server functionality for various data sources including BigQuery.

macOS/Linux Installation

# Create local bin directory if it doesn't exist
mkdir -p ~/.local/bin

# Download and install toolbox (if you have the binary)
# Option 1: If binary is in your downloads or current directory
cp /path/to/toolbox ~/.local/bin/
chmod +x ~/.local/bin/toolbox

# Option 2: Download from a release (if available)
# curl -L https://github.com/stacklok/toolbox/releases/latest/download/toolbox-darwin-arm64 -o ~/.local/bin/toolbox
# chmod +x ~/.local/bin/toolbox

# Verify installation
~/.local/bin/toolbox --help

Windows Installation

# Download the latest version (v0.24.0) for Windows
export VERSION=0.24.0
curl -L -o toolbox.exe "https://storage.googleapis.com/genai-toolbox/v$VERSION/windows/amd64/toolbox.exe"

# Create local bin directory and move toolbox
mkdir -p ~/.local/bin
mv toolbox.exe ~/.local/bin/

# Verify installation
~/.local/bin/toolbox.exe --help

Note: The toolbox binary will be located at C:\Users\<your-username>\.local\bin\toolbox.exe

5. Step 3: Configure Claude Desktop

a. Open Claude Desktop Configuration

Open Claude Desktop
Click your profile icon (bottom-left corner)
Select "Settings"
Click "Developer" from the left menu
Click "Edit Config" button

This opens your claude_desktop_config.json file.

b. Add BigQuery MCP Server Configuration

Add the following configuration to your JSON file:

macOS/Linux:

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/<your-username>/.local/bin/toolbox",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "your-gcp-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/<your-username>/.config/gcloud/keys/your-key-file.json"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "bigquery": {
      "command": "C:\\Users\\<your-username>\\.local\\bin\\toolbox.exe",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "your-gcp-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "C:\\Users\\<your-username>\\Documents\\keys\\your-key-file.json"
      }
    }
  }
}

c. Replace Placeholders

Replace these values with your actual information:

<your-username>: Your system username
your-gcp-project-id: Your GCP project ID (e.g., gcp-mcp-server)
your-key-file.json: The name of your downloaded service account key file

d. Example Configuration

Here's a complete example:

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/<your-username>/.local/bin/toolbox",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "gcp-mcp-server",
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/<your-username>/.config/gcloud/keys/your-key-file.json"
      }
    }
  }
}

e. Save and Restart

Save the configuration file
Completely close Claude Desktop
Reopen Claude Desktop

6. Step 4: Verify MCP Server is Enabled

Open Claude Desktop
Click the "🔌" icon or "Search and Tools" button (next to the prompt input)
Look for gcp-bigquery-billing in the connectors list
Ensure the toggle is enabled (blue/on position)
Your setup includes 5 powerful tools: query_gcp_billing - Flexible queries about GCP costs get_gcp_cost_summary - Total cost summaries by time period get_gcp_costs_by_service - Service-level cost breakdown get_gcp_costs_by_project - Project-level cost breakdown get_gcp_daily_costs - Daily cost trends for analysis

7. Step 5: Test Your Setup

Try these prompts in Claude to verify everything works:

Basic Query Test

Show me my total GCP costs for the last 180 days

Expected: A breakdown of your GCP spending over the past 6 months

Example Output:

View video demonstration

Service Breakdown

What are my top 5 most expensive GCP services this month?

Expected: A table showing top 5 most exepensive per GCP service

Trend Analysis

Analyze my GCP cost trends over the past 90 days. Show me which services have increased the most and provide a visualization

Expected: Trend analysis with insights and possibly a chart

Cross-Region Analysis

Compare my GCP costs across all regions for the last month. Which region is most expensive?

Expected: Regional cost breakdown with comparison

8. Troubleshooting

Issue: "Unable to find default Google Cloud credentials"

Solution:

Verify the GOOGLE_APPLICATION_CREDENTIALS path is correct
Ensure the JSON key file exists at that location
Check file permissions (should be readable by your user)

Issue: "Permission denied" errors when querying

Solution:

Verify your service account has roles/bigquery.dataViewer on the billing export dataset
Check that billing export is enabled and data exists in BigQuery

Issue: "Toolbox not found" or "Command not found"

Solution:

Verify toolbox is installed: ls -la ~/.local/bin/toolbox
Check the path in your config matches the installation location
Ensure the binary is executable: chmod +x ~/.local/bin/toolbox

Issue: MCP server doesn't appear in Claude

Solution:

Check Claude logs: ~/Library/Logs/Claude/mcp-server-bigquery.log (macOS)
Verify JSON syntax is valid (no trailing commas, proper brackets)
Restart Claude Desktop completely (quit from menu bar, not just close window)

9. Security Best Practices

Least Privilege: Only grant the minimum required permissions to your service account
Key Rotation: Rotate service account keys regularly (every 90 days recommended)
Secure Storage: Never store keys in version control or public locations
Audit Access: Regularly review service account usage in GCP audit logs
Use Separate Accounts: Create dedicated service accounts for different purposes

For more details, see our GCP Security Guide (if available).

10. Architecture Diagram

Here's what you've just set up:

flowchart TB
    subgraph Local["Local Machine"]
        Claude["Claude Desktop"]
        Config["claude_desktop_config.json"]
        Toolbox["Toolbox Binary (BigQuery MCP)"]
        SAKey["Service Account Key (JSON)"]
    end

    subgraph GCP["Google Cloud Platform ☁️"]
        SA["Service Account\n(gcp-mcp-dataviewer)"]
        BQ["BigQuery Dataset\n(Billing Export)"]
        IAM["IAM & Permissions"]
    end

    Claude -- reads --> Config
    Claude -- invokes --> Toolbox
    Toolbox -- uses --> SAKey
    SAKey -- authenticates as --> SA
    SA -- authorized by --> IAM
    Toolbox -- queries --> BQ
    BQ -- returns data --> Toolbox
    Toolbox -- sends response --> Claude

    classDef gcp fill:#4285F4,stroke:#000,color:#fff
    class SA,BQ,IAM gcp

11. Next Steps

Explore More Queries: Try complex aggregations and cost forecasting
Combine with Other MCPs: Use alongside AWS or Azure MCP servers for multi-cloud analysis
Automate Reports: Create recurring cost analysis reports with Claude
Set Up Alerts: Monitor for cost anomalies and optimization opportunities

For more GCP MCP server details, see the GCP MCP Server Documentation.