← Back to the dashboard

How to connect Google (2.1, 2.3, 2.4, 6.3)

This sets up route A from the 2.1 plan: a dedicated BlueBoost Google account that approves access once. After that, BlueBoost works on its own. It takes about 30 minutes and costs nothing.

One sign-in covers three things (updated 2026-10-24):

1. Reading Search Console (2.1 search numbers, and 2.4's check of which pages Google has indexed). Read-only.
2. Reading Google Analytics (GA4, for 2.3's visits and leads). Read-only. Card 2.3 isn't built yet, but asking now means you won't have to sign in again when it is.
3. Sending the weekly digest by email (6.3) from the BlueBoost account's Gmail. Send-only: BlueBoost can't read the account's mail.

The exact permission names (scopes) are in db/google-auth.mjs, checked on Google's own pages on 2026-10-24.

You do every click in Google yourself. That includes creating the account, accepting Google's terms and copying the client values. Claude must not do these for you. Never paste a password, client secret or token into chat; the scripts read them from .env, which never goes into git.

Google's screen labels below are as of 2026-10-21 (Parts 2b and 3 updated 2026-10-24). If a label differs, pick the closest match and tell Claude what you saw.

Part 1: Make the BlueBoost Google account (5 minutes)

1. Sign out of Google, or open a private window, so you don't use your personal account by mistake.
2. Go to https://accounts.google.com/signup and create a free account, such as blueboost.blueforest@gmail.com.
3. Save its password in your password manager, and turn on 2-Step Verification under Security.

Why a separate account: if it lives in a person's account, BlueBoost stops when that person leaves or changes their password.

Part 2: Give it Search Console access (2 minutes, done by the property's owner)

1. Go to https://search.google.com/search-console, signed in as whoever owns the BlueForest property.
2. In the property menu at the top left, pick blueforeststudios.com. Note which kind it is:
3. Domain property: it shows just blueforeststudios.com. This is what we expect.
4. URL-prefix property: it shows https://www.blueforeststudios.com/. Tell Claude, because the property name changes.
5. Go to Settings, then Users and permissions, then Add user.
6. Enter the BlueBoost account's email, set Permission to Restricted, and click Add.
7. While you're signed in as owner, pending input #8 asks whether the site is included in "Search generative AI features". If you see that setting, note what it says.

Part 2b: Give it Google Analytics access (2 minutes, done by the GA4 property's owner)

This is for card 2.3. Doing it now saves a trip later.

1. Go to https://analytics.google.com, signed in as whoever administers the BlueForest GA4 property.
2. Click Admin (the gear at the bottom left). Under Property, open Property access management.
3. Click +, then Add users. Enter the BlueBoost account's email, choose the Viewer role, and click Add.
4. Still in Admin, open Property details and note the Property ID (a number such as 123456789). Tell Claude the number; it isn't a secret.

If you don't know who administers GA4, skip this part and tell Claude. The sign-in in Part 6 still works; only 2.3 waits.

Part 3: Make the Google Cloud project (5 minutes, as the BlueBoost account)

1. Go to https://console.cloud.google.com, signed in as the BlueBoost account, and accept the terms if asked.
2. In the project picker at the top, click New project. Name it BlueBoost and click Create. A free Gmail account shows "No organization", which is fine and avoids the key block.
3. Go to APIs & Services, then Library. Enable these three, one at a time: search for the name, open it, and click Enable.
4. Google Search Console API (2.1 and 2.4)
5. Google Analytics Data API (2.3)
6. Gmail API (6.3, sending the digest)
7. If Google asks for billing details, stop and tell Claude. All three are free, and we don't expect them to need billing.

Part 4: Set up the sign-in screen (5 minutes)

1. In the menu, open Google Auth Platform and click Get started.
2. App name: BlueBoost. Support email: the BlueBoost account.
3. Audience: choose External.
4. Contact email: the BlueBoost account. Agree to the policy and click Create.
5. Open Audience and click Publish app, then Confirm. The status must read In production.

This step matters: in "Testing" status, Google's sign-in expires after 7 days and BlueBoost would stop. "In production" without Google's review is allowed for personal use by fewer than 100 users (Google).

Part 5: Make the Desktop client (2 minutes)

1. In Google Auth Platform, open Clients and click Create client.
2. Application type: Desktop app. Name: BlueBoost on Mac. Click Create.
3. Keep the window that shows the Client ID and Client secret open for Part 6. Don't paste them into chat.

Part 6: Sign in once (3 minutes)

1. Open a Terminal and go to the project's db folder: ``bash cd "/Users/chris-blueforest/Claude Code Projects/BlueBoost/db" ``
2. Start the sign-in: ``bash npm run google-login ``
3. Paste the Client ID, press Return, then paste the Client secret and press Return. They're saved in .env.
4. A browser tab opens. Choose the BlueBoost account.
5. Google may show "Google hasn't verified this app". That's expected, because this is our own app and two of its permissions (reading Analytics and sending mail) are ones Google reviews for public apps. Click Advanced, then Go to BlueBoost (unsafe).
6. Google lists three permissions. Tick every box, then click Continue:
7. View Search Console data for your verified sites
8. See and download your Google Analytics data
9. Send email on your behalf The tab says "BlueBoost: sign-in received".
10. Terminal says "Signed in. Saved the refresh token to .env (not shown)." If a box was left unticked, it says "Not all access was allowed" and names what's missing: run npm run google-login again and tick it.

Part 7: Run the check (1 minute)

npm run search-console-check -- sc-domain:blueforeststudios.com

Pass means three PASS lines and a table of 7 days of clicks and impressions.

To confirm the numbers:

1. In Search Console, open Performance.
2. Set Date to Custom, with the same start and end dates the check printed.
3. Leave Search type on Web.
4. Compare total clicks and impressions with the check's total line. They should match.

Tell Claude:

1. Pass or fail, with the FAIL line if there was one.
2. Whether the totals matched the screen.
3. What Part 2 showed: the kind of property, and the AI-features setting.

Claude then:

1. Fills in the site's Search Console property.
2. Replaces the made-up golden file with the real reply (saved in db/tests/output/search-console-sample.json).
3. Marks Piece 1 as passed.

Part 8: A free key for page-speed data (4 minutes, for 2.4)

The technical audit (2.4) gets Core Web Vitals, how fast the site feels to real visitors, from Google's Chrome UX Report. It's free, with no paid tier, but it needs a key (CrUX API, checked 2026-10-23).

1. Go to https://console.cloud.google.com, signed in as the BlueBoost account, with the BlueBoost project selected at the top.
2. Go to APIs & Services, then Library. Search for Chrome UX Report API and click Enable.
3. Go to APIs & Services, then Credentials. Click Create credentials, then API key, and copy the key.
4. Optional but sensible: click Edit API key, and under API restrictions choose Restrict key and tick only Chrome UX Report API. Then the key can't be used for anything else.
5. Save it: in Terminal, in the db folder, run npm run keys. Press Return alone to skip any AI keys you don't have yet, and paste this key when it asks for the Google page-speed key. Don't paste it into chat.

If Google asks for billing details, stop and tell Claude. This API is free, and we don't expect it to need billing.

If something breaks