/seo-google

Google API Authentication Setup

Overview

Three credential types serve different APIs:

Step 1: Create a Google Cloud Project

1. Go to console.cloud.google.com
2. Click Select a project > New Project
3. Name it (e.g., "Claude SEO") and note the project ID
4. Select the project after creation

Step 2: Enable APIs

Navigate to APIs & Services > Library and enable:

Step 3: Create an API Key

1. APIs & Services > Credentials > Create Credentials > API key
2. Click Restrict key:
   • Under API restrictions, select: PageSpeed Insights API, Chrome UX Report API, Knowledge Graph Search API
3. Copy the generated API key and store it securely

Step 4: Create a Service Account

1. IAM & Admin > Service Accounts > Create Service Account
2. Name: claude-seo (or similar)
3. Skip optional permissions steps
4. Click on the created service account > Keys > Add Key > Create new key > JSON
5. Download the JSON file and store it securely (e.g., ~/.config/claude-seo/service_account.json)

The JSON file looks like:

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "<service-account-private-key>",
  "client_email": "<service-account-identifier>",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token"
}

The client_email field is what you add to GSC and GA4.

Step 5: Grant Search Console Access

1. Go to Google Search Console
2. Select your property
3. Settings > Users and permissions > Add user
4. Paste the service account client_email
5. Set permission level:
   • Full for read-only (Search Analytics, URL Inspection, Sitemaps)
   • Owner if you also need the Indexing API

Step 6: Grant GA4 Access

1. Go to Google Analytics
2. Admin > Property Access Management > Add users (the + icon)
3. Paste the service account client_email
4. Set role: Viewer (minimum for read-only reporting)
5. Note the numeric property ID from Admin > Property Details (e.g., 123456789)

Step 7: Create Config File

mkdir -p ~/.config/claude-seo

Save to ~/.config/claude-seo/google-api.json:

{
  "service_account_path": "~/.config/claude-seo/service_account.json",
  "api_key": "<GOOGLE_API_KEY>",
  "default_property": "sc-domain:example.com",
  "ga4_property_id": "properties/123456789"
}

Property URL Formats

Step 8: Verify Setup

"${CLAUDE_PLUGIN_ROOT}/scripts/claude-seo" run google_auth.py --check

Expected output at Tier 2 (full):

Credential Tier: 2 -- Full (API key + Service Account + GA4)

  [OK] PageSpeed Insights v5
  [OK] Chrome UX Report (CrUX) API
  [OK] CrUX History API
  [OK] Google Search Console API
       Service account: configured
  [OK] Google Indexing API v3
  [OK] GA4 Data API v1beta

Environment Variable Alternatives

Instead of (or in addition to) the config file:

OAuth Scopes Used

Troubleshooting