Connect Claude AI to your BigQuery dataset via MCP (Model Context Protocol) so your team can ask natural language questions about their data — no SQL skills needed.

What You Can Do #

Once connected, your team can ask questions like:

• “How many people abandon checkout after entering their email?”
• “What % of users who reach add_payment_info complete a booking?”
• “Show me all abandoned carts with email addresses from the last 30 days”
• “Which products have the highest abandonment rate?”
• “What is the average time between payment_initiated and booking_confirmed?”

The technology: MCP (Model Context Protocol) connects Claude directly to BigQuery. You ask in plain English, Claude writes the SQL, runs it, and explains the results.

Choose Your Front End #

There are 3 options for accessing your data. All use the same MCP connection to BigQuery underneath.

Option A: Claude Desktop App (Recommended) #

• What it is: A desktop chat app — looks exactly like ChatGPT or claude.ai
• Experience: Open app, type question in plain English, get answer
• Platform: Mac and Windows
• Download: claude.ai/download
• Cost: Requires Claude Pro subscription ($20/month per user)
• Best for: Non-technical team members, marketing managers, business owners

Option B: Claude Code (Terminal) #

• What it is: AI assistant that runs in the terminal
• Experience: Open terminal, type question, get answer (same natural language)
• Install: npm install -g @anthropic-ai/claude-code
• Cost: Requires Anthropic API key (pay-per-use, very low cost)
• Best for: Technical team members, developers, power users
• Bonus: Can also write scripts, automate reports, export data to files

Option C: Google Gemini CLI #

• What it is: Google own AI tool with MCP support
• Experience: Command line based
• Cost: Free with Google account
• Best for: Teams already deep in Google ecosystem
• Downside: Less polished, command-line only, Gemini not as strong as Claude for data analysis

Comparison #

Recommendation: Start with Claude Desktop for day-to-day team use. Add Claude Code for developers who want terminal access and automation.

Architecture #

Your Website --> Events --> Transmute Engine --> BigQuery
                                                    |
                                          MCP Server (read-only)
                                                    |
                                 +------------------+------------------+
                                 |                  |                  |
                          Claude Desktop       Claude Code       Gemini CLI
                           (Chat App)          (Terminal)        (Terminal)
                                 |                  |                  |
                           Your Team           Developers        Google Users
                         asks questions      automate/script    (free option)

Requirements #

• A BigQuery dataset with data flowing from Transmute Engine (see Create a BigQuery Dataset)
• Node.js 18+ installed on the machine that will run Claude
• Claude Desktop app or Claude Code installed
• Your BigQuery Service Account JSON key file

Step 1 — Install Claude Desktop #

1. Download from claude.ai/download
2. Install and sign in with a Claude Pro account ($20/month)
3. Verify Node.js is installed: open a terminal and run node --version (must be 18+)

Step 2 — Your Service Account JSON Key File #

When you set up BigQuery (see Create a BigQuery Dataset), you created a Service Account and downloaded a JSON key file. This is what the file looks like inside:

{
  "type": "service_account",
  "project_id": "seresa-prod",
  "private_key_id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "private_key": "-----BEGIN PRIVATE KEY-----nMIIEvgIBADANBgkqhkiG9w0BAQEFAASC...n...(key content)...n...-----END PRIVATE KEY-----n",
  "client_email": "dummy-to-hell@gotohell.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/transmute-engine%40seresa-prod.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

The key fields you will need later are project_id and the file itself.

Find or Download Your Key #

If you have lost your JSON key file, you can create a new one:

1. Go to Google Cloud Console > IAM & Admin > Service Accounts
2. Make sure your project is selected in the project dropdown at the top
3. Click on your service account (e.g. dummy-to-hell@gotohell.com)
4. Go to the Keys tab
5. Click Add Key > Create new key
6. Select JSON and click Create

Security: Each time you create a new key, the old key still works. Delete old keys you no longer use from the Keys tab.

Step 3 — Place Your JSON Key File #

Copy your BigQuery Service Account JSON key file to a secure location on your computer. We recommend creating a credentials folder in your home directory:

To create the folder and move your key file (macOS):

mkdir -p ~/credentials
mv ~/Downloads/your-key-file.json ~/credentials/seresa-bigquery-key.json

Important: When you use this path in the Claude config file (next step), you must use the full absolute path — not ~. To find your full home path, open Terminal and run:

echo $HOME

This will output something like /Users/matt or /Users/sarah. Use that in the config file.

Security: Never put the key file in a git repo, shared folder, or public location.

Step 4 — Configure Claude Desktop MCP #

Find the Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration (replace the placeholder values with your own):

{
  "mcpServers": {
    "seresa-bigquery": {
      "command": "npx",
      "args": [
        "-y",
        "@ergut/mcp-bigquery-server",
        "--project-id", "YOUR-GCP-PROJECT-ID",
        "--location", "asia-southeast1",
        "--key-file", "/Users/YOUR_USERNAME/credentials/seresa-bigquery-key.json"
      ]
    }
  }
}

⚠️ Important — Use the full absolute path for the key file. Do not use ~ (tilde) in the path. JSON config files are read by Node.js, which does not expand ~ to your home directory. Using ~ will cause a “Could not attach to MCP server” error.

Replace:

• YOUR-GCP-PROJECT-ID — your Google Cloud project ID (found in your JSON key file as project_id)
• asia-southeast1 — the region of your dataset (e.g. asia-southeast1, US)
• /Users/YOUR_USERNAME/credentials/seresa-bigquery-key.json — the full absolute path to your JSON key file from Step 3

The service account key file controls which project and datasets Claude can access.

Step 5 — Restart and Verify #

1. Fully quit Claude Desktop (not just close the window — use Cmd+Q on Mac or fully exit on Windows)
2. Reopen Claude Desktop
3. Click the + button below the chat input box
4. Select Connectors from the menu
5. Verify that seresa-bigquery is listed and the toggle is switched ON (blue)

If the toggle is blue, your MCP server is connected and ready to use.

Step 6 — Test the Connection #

Ask Claude these test questions:

1. “List all tables in my BigQuery project”
2. “Show me the schema for the events table”
3. “What is the total count of records?”
4. “Show me the most recent 10 events”

If these return results, your MCP connection is working.

Alternative: Set Up Claude Code (Terminal) #

For developers or power users who prefer the terminal:

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Add BigQuery MCP server
claude mcp add seresa-bigquery --scope user --transport stdio -- \
  npx -y @ergut/mcp-bigquery-server \
  --project-id YOUR-GCP-PROJECT-ID \
  --location YOUR-DATASET-LOCATION \
  --key-file /Users/YOUR_USERNAME/credentials/seresa-bigquery-key.json

Then run claude in your terminal and start asking questions.

Example Queries #

Once connected, your team can ask questions in plain English:

Campaign performance:

• “Show me Facebook campaign ROI for last 6 months”
• “Which Google Ads campaigns have cost per acquisition under $50?”
• “Compare email campaign performance: newsletter vs abandoned cart”

Customer behavior:

• “What is our repeat purchase rate by acquisition channel?”
• “How long does the average customer take from first visit to purchase?”
• “Segment customers by lifetime value — top 10%, middle 50%, bottom 40%”

Product intelligence:

• “Which products are frequently bought together?”
• “What is our best-selling product by month over the last year?”
• “Show product category performance year-over-year”

Funnel analysis:

• “How many people abandon checkout after entering their email?”
• “For all sessions that reached add_payment_info, what percentage completed a purchase?”
• “Give me email addresses for abandoned carts in the last 60 days”

Claude writes the SQL, runs it against BigQuery, and explains the results in plain language. Zero SQL knowledge required.

How It Works Behind the Scenes #

Your question (plain English): “Which campaigns drove the most revenue in Q4?”

What happens:

1. Claude understands your question
2. Inspects your BigQuery schema to find the right tables and columns
3. Writes the appropriate SQL query
4. MCP executes the query against BigQuery (read-only)
5. Claude receives the results
6. Explains the answer in plain language

What you see: “Your top campaign was holiday_sale with $145,230 revenue from 1,847 purchases (average order $78.62). Second was black_friday at $98,450 from 1,203 purchases…”

Security #

About the BigQuery MCP Connection #

MCP (Model Context Protocol) is an open standard created by Anthropic that lets AI tools like Claude connect to external data sources. An MCP server acts as a bridge — it sits between Claude and your BigQuery data, translating your plain English questions into SQL queries and returning the results.

There are two MCP servers available for BigQuery. We use Option A for all client setups.

Option A: ergut MCP Server (What We Use) #

@ergut/mcp-bigquery-server is an open-source MCP server built by Ergut, a developer focused on AI data tooling. It runs locally on your computer via npx (part of Node.js) and connects to BigQuery using your service account JSON key file.

When you ask Claude a question, this MCP server receives the SQL query that Claude generates, runs it against your BigQuery dataset, and returns the results — all read-only. It has a built-in 1GB query limit to prevent accidental large scans that could increase costs.

This is our recommended option for all clients. It is lightweight, safe, and takes minutes to set up.

References:

• npm package — @ergut/mcp-bigquery-server
• GitHub repository — ergut/mcp-bigquery-server
• MCP (Model Context Protocol) — official specification

Option B: Google Official Remote MCP Server #

bigquery.googleapis.com/mcp is Google’s own MCP server for BigQuery. Unlike ergut’s server which runs locally on your machine, Google’s server is fully hosted and managed remotely by Google Cloud. It was auto-enabled on BigQuery projects from March 2026.

It offers a richer set of tools — beyond just running queries, it can browse schemas, list tables, and inspect column details. However, it requires OAuth 2.0 authentication (a multi-step browser-based login flow) rather than a simple JSON key file, making it significantly harder to set up for non-technical users.

Not recommended for most clients at this time. The OAuth setup is complex and unnecessary for read-only analytics. If Google adds service account key file support in future, we will revisit this recommendation.

References:

• Google Cloud — BigQuery MCP Server documentation
• Google Cloud Blog — BigQuery MCP announcement

Troubleshooting #

Service Setup Fee #

Prefer to have the BigQuery + AI integration set up for you? Our team can handle the full setup on your behalf.

This is a one-off pre-paid fee (2026 rates) and includes:

• MCP server configuration for Claude Desktop and/or Claude Code
• Connecting to your existing BigQuery dataset
• Security review and key file setup
• Full end-to-end testing with your data
• 30-minute walkthrough with your team

To arrange setup, contact dummy-to-hell@gotohell.com.