Google Drive + Microsoft Clarity setup

GoHighLevel sites in SEO Navigator MCP can be linked to:

• One Google Drive folder — per-user OAuth (drive.file scope only), used by drive_get_site_folder, drive_list_site_files, drive_read_file, drive_get_baseline, and (when allowed) drive_save_audit.
• One Microsoft Clarity project — per-site Data Export token, used by the four clarity_* read tools.

You only need to do each side once per Worker / per site, not per Claude conversation.

---

1. Google Drive — per-user OAuth

One-time Worker setup (super-admin)

1. Go to https://console.cloud.google.com → create or pick a project.

2. APIs & Services → Library → enable Google Drive API.

3. APIs & Services → OAuth consent screen → set up “External” (or “Internal” if your Google Workspace owns the Drive folders). Add the scopes .../auth/drive.file and .../auth/userinfo.email. Both are non-sensitive — no Google verification is required.

4. Publish the app (button on the OAuth consent screen page). Status flips from “Testing” to “In production”. Without this step only emails added to “Test users” can authorise.

5. APIs & Services → Credentials → Create credentials → OAuth client ID → application type Web application. Add the redirect URI:

   https://<worker-host>/admin/oauth/google/callback

   For the reference Worker that’s:

   https://seo-navigator-mcp.autumn-recipe-cac7.workers.dev/admin/oauth/google/callback

6. Copy the Client ID and Client secret. Set them as Worker secrets:

   "<client-id>"     | npx wrangler secret put GOOGLE_OAUTH_CLIENT_ID
   "<client-secret>" | npx wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET

   No npx wrangler deploy needed — secrets are picked up on the next request.

Why drive.file scope? It is the only non-sensitive Drive scope. Google does not require app review for it. The trade-off: this app can only later read files it has created via API OR files the user explicitly shares with it via the Google Drive Picker. For the CRM-audit workflow (write baseline.md, write weekly audit reports, read them back to diff) that’s exactly what we need.

Per-user connect

Each Worker user that needs Drive access clicks Connect Google once at /admin/users. The flow:

1. Worker redirects to accounts.google.com with prompt=consent + access_type=offline so Google returns a refresh token.
2. After the user approves, Google calls back to /admin/oauth/google/callback?code=…&state=….
3. Worker exchanges the code → tokens, encrypts the refresh token with MASTER_TOKEN, and stores it in the user_oauth_tokens D1 table.
4. The users table shows ✓ + the connected Google email.

Super-admin can also initiate a connect on behalf of any user via /admin/oauth/google/start?uid=<user_id>. Regular users can only connect their own account.

To disconnect: click Disconnect in the users table. This deletes the row in user_oauth_tokens. Google’s revocation page (myaccount.google.com/connections) is a separate revocation — recommended for full cleanup if you want Google to forget the grant too.

Linking a Drive folder to a site

In /admin/sites/<site_id> (only visible for platform = gohighlevel):

Field	Notes
Drive user id	The Worker user id (slug) whose Google OAuth reaches the folder.
Folder id	The literal Drive folder ID. Find it in the URL: drive.google.com/drive/folders/<THIS-PART>.
Folder label	Optional human-readable label, e.g. Clients/Acme/CRM-Audits.

The connected Google account must have access to the folder. With drive.file scope the app can write into any folder the connected account can write to (so create the folder in that account’s Drive, or share an existing folder with at least Editor permission). After the first drive_save_audit writes a file in the folder, those files are visible to the app on subsequent reads.

Super-admin write gate

Drive writes (drive_save_audit) are default OFF, following the CRM-audit “read-only first 90 days” guidance. Toggle Allow Drive writes in the site form’s Danger Zone (super-admin only) to enable. Read tools (drive_get_site_folder, drive_list_site_files, drive_read_file, drive_get_baseline) work as soon as the folder is linked and the user has connected Google.

---

2. Microsoft Clarity — per-site Data Export token

Get a token

1. Open the Clarity project at https://clarity.microsoft.com.
2. Settings → Data Export (under Settings in the left rail).
3. Generate new API token. Copy the token immediately — Clarity shows it only once.
4. Note the project id (usually visible on the Settings page, or as the cl_pid query parameter in the dashboard URL).

Link to a site

In /admin/sites/<site_id> (only visible for platform = gohighlevel):

Field	Notes
Clarity project id	The literal project id.
Data Export token	Paste once. Encrypted with MASTER_TOKEN before it lands in D1; never returned in plaintext afterwards. Leave blank on edit to keep the existing token.

Tool surface

All four Clarity tools are read-only; no super-admin gate is required.

• clarity_get_project_info — quick probe; useful after rotating the token.
• clarity_get_metrics — pass num_of_days (1-3) + up to 3 dimensions (Browser, Device, OS, Country, Source, Medium, Campaign, Channel, URL).
• clarity_get_session_recordings — aggregate session/traffic/engagement metric blocks + a dashboard_url deep link the caller can open in clarity.microsoft.com.
• clarity_get_heatmap_metrics — aggregate rage/dead-click + scroll metric blocks + a heatmaps deep link.

The public Data Export API is intentionally aggregate-only. Clarity does NOT expose per-session URLs or pixel-level heatmap data via the public API. The *_session_recordings and *_heatmap_metrics tools return aggregates only and link out to the dashboard for the actual recordings/heatmaps. See CRM-audit workflow §3.1 for what stays manual.

Daily snapshots (auto-collected)

Clarity’s numOfDays param caps at 3, which makes 7- or 30-day baselines impossible from a single call. To work around this the worker runs a daily cron at 01:30 UTC that calls clarity_get_metrics(num_of_days=1) for every linked site and persists the raw metric blocks into clarity_daily_snapshots (D1). Tools then read longer windows from the snapshot table:

• clarity_get_historical_metrics(site_id, days_back) returns whatever’s in the table over the window, plus a days_missing count so callers know when the cron hasn’t filled in yet.
• ghl_bootstrap_baseline reads the snapshot table to render the Clarity friction section of baseline.md. For the first 30 days after linking, the snapshot table won’t be full — supplement from the Clarity dashboard for that initial period.

No setup needed beyond linking the project + token here. The cron auto-discovers any site with clarity_project_id set. Failures are isolated per site and logged to Workers Observability (one bad token doesn’t block the others).

---

3. Verifying the setup

Run diagnose_site on the GHL site. The GHL branch returns:

{
  "platform": "gohighlevel",
  "site_config": {
    "allow_gohighlevel_write": false,
    "allow_drive_write": true
  },
  "drive": {
    "linked": true,
    "user_id": "support",
    "folder_id": "1ZVjbsFPqtsI4A_-0TgJ2XrFGXidd_S9E",
    "folder_path": "CRM Audit",
    "allow_drive_write": true,
    "reachable": true,
    "folder_name": "CRM Audit",
    "web_view_link": "https://drive.google.com/drive/folders/1ZVjbsFPqtsI4A_-0TgJ2XrFGXidd_S9E",
    "error": null
  },
  "clarity": {
    "linked": true,
    "project_id": "jb9okwb298",
    "reachable": true,
    "block_count": 16,
    "error": null
  }
}

Common errors:

Symptom	Fix
drive.reachable: false with E_MISSING_OAUTH_TOKEN	The Worker user has not connected Google. Visit /admin/users and click Connect Google.
drive.reachable: false with 404	Folder ID wrong, or the folder is not accessible from the connected Google account. Share the folder with that account at Editor level.
drive.reachable: false with invalid_grant	The user revoked the app at myaccount.google.com/connections. Reconnect at /admin/users.
clarity.reachable: false with 401	Data Export token is wrong, revoked, or for a different Clarity project. Rotate at Clarity → Settings → Data Export, then PUT the new token in the site form.
drive.linked: false / clarity.linked: false	Site form fields are blank. Fill them in /admin/sites/<site_id>.

---

Related

• CRM-audit workflow — full CRM-audit coverage with prompt templates.
• GoHighLevel prerequisites — PIT + location ID setup.
• Tokens & scoping — which MCP tools the Claude Desktop token can call.