Marketer MCP Setup Guide

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

Quick Setup (Recommended)

We've packaged the entire setup into a single script per OS. Download it and run it — it installs the Google Cloud CLI, downloads the MCP toolbox, registers the BigQuery connection in Claude Code, and walks you through Google sign-in. Total time ~5 minutes after Claude Code is installed.

chmod +x ~/Downloads/setup-mac.sh
~/Downloads/setup-mac.sh

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
.\Downloads\marketer-pipeline-setup-windows.ps1

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

Step 1 — Install Claude Code

Claude Code is the AI assistant you'll use for everything. Install it before running the setup script.

Once Claude is open and you're signed in, don't close it — the setup script needs the claude command to be available in your terminal.

Step 2 — Open Your Terminal

Everything in this setup is done by typing commands into a terminal window. Here's how to open one.

Step 3 — Run the Setup Script

This script handles everything — installing the Google Cloud CLI, downloading the toolbox, registering the BigQuery connection in Claude, and authenticating your Google account. You only need to run it once.

The download links are also in Quick Setup at the top of the page.

chmod +x ~/Downloads/setup-mac.sh
~/Downloads/setup-mac.sh

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Unblock-File -Path "$env:USERPROFILE\Downloads\marketer-pipeline-setup-windows.ps1"

.\Downloads\marketer-pipeline-setup-windows.ps1

Step 4 — Test It Works

Open a fresh Claude conversation and ask:

Claude should list the client projects Alyssa has provisioned for you. If it does, you're done — BigQuery data is now available in every Claude conversation.

If it returns an error or an empty list, see Troubleshooting below or message Timothy.

Manual Setup (Reference)

The script in Step 3 does all of this automatically. These steps are here in case you need to re-run one piece, or if the script fails partway through.

brew install --cask google-cloud-sdk

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

mkdir -p ~/bin
curl -fsSL -o ~/bin/toolbox https://storage.googleapis.com/genai-toolbox/v0.32.0/darwin/arm64/toolbox
chmod +x ~/bin/toolbox
xattr -d com.apple.quarantine ~/bin/toolbox 2>/dev/null || true

mkdir -p ~/bin
curl -fsSL -o ~/bin/toolbox https://storage.googleapis.com/genai-toolbox/v0.32.0/darwin/amd64/toolbox
chmod +x ~/bin/toolbox
xattr -d com.apple.quarantine ~/bin/toolbox 2>/dev/null || true

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

gcloud auth application-default login

sudo mkdir -p "/Library/Application Support/ClaudeCode"
sudo tee "/Library/Application Support/ClaudeCode/managed-mcp.json" > /dev/null <<'EOF'
{
  "mcpServers": {
    "bigquery": {
      "type": "stdio",
      "command": "/Users/YOURNAME/bin/toolbox",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": { "BIGQUERY_PROJECT": "marty-search-console-ga4-api" }
    }
  }
}
EOF

$dir = "C:\Program Files\ClaudeCode"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
@'
{
  "mcpServers": {
    "bigquery": {
      "type": "stdio",
      "command": "C:\\Users\\YOURNAME\\bin\\toolbox.exe",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": { "BIGQUERY_PROJECT": "marty-search-console-ga4-api" }
    }
  }
}
'@ | Set-Content -Path "$dir\managed-mcp.json" -Encoding UTF8

claude mcp add --scope user bigquery ~/bin/toolbox \
  --env BIGQUERY_PROJECT=marty-search-console-ga4-api \
  -- --prebuilt bigquery --stdio

claude mcp add --scope user bigquery "$env:USERPROFILE\bin\toolbox.exe" `
  --env BIGQUERY_PROJECT=marty-search-console-ga4-api `
  -- --prebuilt bigquery --stdio

claude mcp list

{
  "mcpServers": {
    "bigquery": {
      "command": "/Users/YOURNAME/bin/toolbox",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "marty-search-console-ga4-api"
      }
    }
  }
}

{
  "mcpServers": {
    "bigquery": {
      "command": "C:\\Users\\YOURNAME\\bin\\toolbox.exe",
      "args": ["--prebuilt", "bigquery", "--stdio"],
      "env": {
        "BIGQUERY_PROJECT": "marty-search-console-ga4-api"
      }
    }
  }
}

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).