GAGA4 MCPv2.11.9

Agent skill

GCP Service Account Setup for GA4 Data API

Step-by-step playbook to authenticate the GA4 MCP server using a Google Cloud Platform (GCP) Service Account.

This is the standard, enterprise-grade authentication method:

  • Offline & Headless: Requires no interactive browser popups or OAuth consent screens.
  • Persistent: Service account JSON keys never expire (unlike user OAuth tokens).
  • Least-Privilege: Grants read-only Viewer access exclusively to the target GA4 property.

1. Quick Setup via gcloud CLI (Fastest — 60 Seconds)

If you have the gcloud CLI installed, run these 4 commands in your terminal:

bash
# 1. Set your target GCP Project ID
export GCP_PROJECT_ID="$(gcloud config get-value project)"

# 2. Enable the Google Analytics Data API v1beta
gcloud services enable analyticsdata.googleapis.com --project="$GCP_PROJECT_ID"

# 3. Create a dedicated Service Account for the MCP server
gcloud iam service-accounts create ga4-mcp-reader \
  --display-name="GA4 MCP Reader" \
  --description="Read-only service account for GA4 Model Context Protocol" \
  --project="$GCP_PROJECT_ID"

# 4. Generate and download the JSON key file
mkdir -p ~/.config/ga4-mcp
gcloud iam service-accounts keys create ~/.config/ga4-mcp/service-account.json \
  --iam-account="ga4-mcp-reader@${GCP_PROJECT_ID}.iam.gserviceaccount.com" \
  --project="$GCP_PROJECT_ID"

Your service account email will be: ga4-mcp-reader@<YOUR_PROJECT_ID>.iam.gserviceaccount.com


2. Manual Setup via Google Cloud Console (GUI Path)

If you do not have gcloud CLI installed:

  1. Open Google Cloud Console:

Go to console.cloud.google.com and create or select a project.

  1. Enable the API:

Navigate to APIs & Services > Library, search for Google Analytics Data API, and click Enable.

  1. Create Service Account:

Navigate to IAM & Admin > Service Accounts, click + Create Service Account. - Name: ga4-mcp-reader - Description: Read-only GA4 MCP reader - Role: Skip GCP role assignment (GA4 permissions are managed inside Google Analytics, not GCP). Click Done.

  1. Download JSON Key:

Click on the newly created service account > go to the Keys tab > click Add Key > Create new key > select JSON > click Create. Save the downloaded file to a permanent path, e.g.: ~/.config/ga4-mcp/service-account.json


3. Grant Viewer Access in Google Analytics

⚠️ CRITICAL STEP: The service account cannot read your analytics until you explicitly add its email as a Viewer in Google Analytics.

  1. Open analytics.google.com.
  2. Click the gear icon (Admin) in the bottom-left corner.
  3. Under the Property column, click Property access management.
  4. Click the blue + button in the top-right corner and select Add users.
  5. Enter the service account email (e.g. [email protected] or the client_email value inside your JSON key).
  6. Under Standard roles, select Viewer (read-only).
  7. Uncheck "Notify SDK users by email" and click Add.

4. Find Your Numeric GA4 Property ID

GA4 requires the numeric Property ID, NOT the data stream Measurement ID:

  • ❌ Wrong: G-ABC123XYZ (Measurement ID — for website tracking tags, rejected by API)
  • ✔️ Correct: 123456789 (Numeric Property ID — for Data API queries)

Where to find it:

  1. In Google Analytics, click Admin (gear icon).
  2. Under Property, click Property details.
  3. The numeric Property ID is displayed in the top right (e.g., 362847407).

5. Configure Your MCP Client Harness

Update your client configuration file with the absolute path to your JSON key and your numeric Property ID.

Claude Desktop

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

json
{
  "mcpServers": {
    "google-analytics": {
      "command": "uvx",
      "args": ["google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/YOUR_USER/.config/ga4-mcp/service-account.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

Cursor

File: ~/.cursor/mcp.json or .cursor/mcp.json in your workspace:

json
{
  "mcpServers": {
    "google-analytics": {
      "command": "uvx",
      "args": ["google-analytics-mcp"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/Users/YOUR_USER/.config/ga4-mcp/service-account.json",
        "GA4_PROPERTY_ID": "123456789"
      }
    }
  }
}

Claude Code

bash
claude mcp add --env GA4_PROPERTY_ID=123456789 --env GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/key.json --transport stdio google-analytics -- uvx google-analytics-mcp

6. Verification

Restart your AI harness and prompt your agent:

text
List my GA4 properties.

If it returns your property details and account name, your service account is configured and authenticated.