Marketer MCP Setup Guide

Five steps to connect Claude to BigQuery and start asking plain-English questions about client data.

What This Enables

What this enables today:

• Marketers ask questions like "Which channel had the best ROAS last week?" directly inside Claude
• Claude inspects the BigQuery schema, writes the SQL itself, runs it, and returns a marketer-friendly summary
• All access is read-only at multiple layers, so marketers cannot accidentally damage client data

Proof of Progress

Step 1 — Install Google Cloud CLI

brew install --cask google-cloud-sdk

curl https://sdk.cloud.google.com | bash
exec -l $SHELL

Verify (works on either OS):

gcloud --version

Step 2 — Install MCP Toolbox

mkdir -p ~/bin && cd ~/bin
curl -O https://storage.googleapis.com/genai-toolbox/v0.32.0/darwin/arm64/toolbox
chmod +x toolbox

$dir = "$env:USERPROFILE\bin"
New-Item -ItemType Directory -Force -Path $dir
Invoke-WebRequest -Uri "https://storage.googleapis.com/genai-toolbox/v0.32.0/windows/amd64/toolbox.exe" -OutFile "$dir\toolbox.exe"

Verify (works on either OS):

./toolbox --version

Step 3 — Authenticate to Google

Run the following command (same on both platforms):

gcloud auth application-default login

A browser window opens. Sign in as your AimClear Google account (e.g., amber@aimclear.com). Approve the requested scopes.

This creates a credentials file stored locally:

Step 4 — Configure Claude

Option A — Claude Code (recommended for now)

claude mcp add --scope user bigquery ~/bin/toolbox -- --prebuilt bigquery --stdio

claude mcp add --scope user bigquery "$env:USERPROFILE\bin\toolbox.exe" -- --prebuilt bigquery --stdio

This single entry covers all client projects — no separate entry per client, no project ID needed. Access to each project is controlled entirely by Google Cloud IAM on the GCP side.

Verify (works on either OS):

claude mcp list

You should see bigquery — ✓ Connected. If it shows ✗ Failed to connect, see Troubleshooting below.

Option B — Claude Desktop

Edit (or create) the config file:

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOURNAME/bin/toolbox",
      "args": ["--prebuilt", "bigquery", "--stdio"]
    }
  }
}

{
  "mcpServers": {
    "bigquery": {
      "command": "C:\\Users\\YOURNAME\\bin\\toolbox.exe",
      "args": ["--prebuilt", "bigquery", "--stdio"]
    }
  }
}

No project ID needed in the config — one entry covers all clients.

Restart Claude Desktop fully (quit + reopen) for the change to take effect.

Step 5 — Test It Works

In a fresh Claude conversation, ask:

You should see Claude call list_dataset_ids and report back with the actual dataset names. If yes, you're done.

Daily Use

Good question patterns

Marketers don't need to know SQL or BigQuery internals. Just ask in natural language. Examples that work well:

• "Summarize last week's paid media performance across channels."
• "Which audiences had the highest revenue per session in the last 30 days?"
• "What landing pages are getting the most organic traffic this month? Has that changed vs. last month?"
• "Why did sessions drop on Tuesday? Was it a specific source?"
• "Give me a 3-bullet summary I could put in a client status email about Marty's traffic last week."

Just refer to the client by name — Claude will look up which project they're in and route the query there. Example: "For the Amsoil account, how did paid search perform last week?"

Things to know

• Each query costs money. BigQuery charges by data scanned (~$5 per TB). Most queries are pennies, but a query that scans millions of rows can add up. Claude will write efficient queries by default; if you ask for a giant unfiltered scan, it'll do it.
• Data freshness depends on each client's ingestion setup. GA4 → BigQuery exports are typically 24-48h delayed. Search Console exports are similar. Don't expect "real-time" answers.
• Claude can be wrong. The SQL it generates is grounded in real schema, but it can still misinterpret a column. Sanity-check before sharing externally — eyeball the numbers, ask Claude to show its SQL.
• Audit logs exist. Every query you run is logged with your Google identity. This is a feature, not a worry: it means we can always figure out what was asked, by whom, when.

If something looks weird

• Ask Claude to "show me the SQL you ran" — it'll print it
• Ask "what columns are actually in the table you queried?" — confirms it's reading the right schema
• Ask "are there other tables that might be more relevant?" — Claude often picks the simplest table; sometimes a richer one exists

FAQ

Q: Can I use this for clients I don't normally work with?

Only if you've been added to that client's IAM grants. Ask your account lead to coordinate with Alyssa.

Q: My answer looks wrong. What do I do?

Ask Claude to show the SQL it ran and explain its logic. If the SQL looks wrong, ask Claude to try a different approach. If it consistently struggles, message Timothy — the schema may need better documentation.

Q: Can I save a question/dashboard?

Not yet. For now, repeat the question or save the answer in a doc. Saved queries / saved views is on the roadmap.

Q: Can I export the data I get back to Excel / Sheets / Looker?

Claude can format results as a CSV-shaped table that you copy out. For larger exports, we'd build a different tool — this MCP is optimized for "quick questions in plain English," not "pull a 50K-row dataset."

Troubleshooting

bigquery-X — ✗ Failed to connect after claude mcp list

Check, in order:

1. Toolbox binary is present and executable: ~/bin/toolbox --version should print a version
2. ADC is set up: gcloud auth application-default print-access-token should print a token
3. The configured BIGQUERY_PROJECT exists and you have access: gcloud projects describe PROJECT_ID
4. MCP service is enabled on the project: check with Alyssa

Error 403: BigQuery: Permission denied while getting Drive credentials

The query touches a Sheets-backed external table but ADC lacks Drive scope. Re-auth with:

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/bigquery

Error 403: SERVICE_DISABLED: Data Analytics API with Gemini has not been used

Only the ask_data_insights tool needs this. Either:

• Enable: gcloud services enable geminidataanalytics.googleapis.com --project=PROJECT_ID (Alyssa handles this)
• Or just don't use that specific tool — execute_sql covers the same use cases

Claude Desktop config not picked up

Restart Claude Desktop fully (quit + reopen), don't just close the window. On macOS: Cmd+Q. On Windows: right-click the tray icon → Quit, then reopen.

Claude Code MCP showing as connected but tools not appearing in conversation

Start a fresh Claude Code session — MCP tools are registered at session start. /reload-plugins does NOT reload MCP servers (it's for plugins/skills/agents/hooks).