google-analytics

Google Analytics 4 Reporting

Query your GA4 property using natural language — traffic, pages, users, events, behavior metrics, organic landing-page quality, ecommerce revenue, channel mix, and SEO experiment follow-up.

Growth-Intelligence Principle

Do not treat GA4 as a static reporting dashboard. Use it to connect acquisition to business outcomes:

traffic source -> landing page -> engagement -> conversion/revenue -> SEO action/learning

When doing SEO work, pair GA4 with Google Search Console when possible:

• GSC = queries, impressions, clicks, CTR, rankings
• GA4 = sessions, engagement, conversions, revenue

Do not invent missing analytics metrics. If conversions, revenue, ecommerce events, or dimensions are unavailable, say so clearly.

Prerequisites & Setup

Before any query, verify the MCP server is available. Check if these tools exist: runReport, getPageViews, getActiveUsers, getEvents, getUserBehavior.

If the tools are NOT available, walk the user through setup:

Step 1: Install the MCP Server

Ask the user to create or edit .mcp.json in their project root:

{
  "mcpServers": {
    "google-analytics": {
      "command": "npx",
      "args": ["-y", "mcp-server-google-analytics"],
      "env": {
        "GOOGLE_CLIENT_EMAIL": "<service-account-email>",
        "GOOGLE_PRIVATE_KEY": "<private-key-from-json>",
        "GA_PROPERTY_ID": "<numeric-property-id>"
      }
    }
  }
}

Step 2: Get Credentials

Guide the user through these steps:

1. Google Cloud Console — Go to https://console.cloud.google.com/
2. Create or select a project
3. Enable the Analytics Data API — APIs & Services > Library > search "Analytics Data API" > Enable
4. Create a service account — IAM & Admin > Service Accounts > Create Service Account
5. Generate a JSON key — click the service account > Keys > Add Key > JSON > Download
6. Extract values from the JSON file:

• client_email → use as GOOGLE_CLIENT_EMAIL
• private_key → use as GOOGLE_PRIVATE_KEY

1. Grant access in GA4 — Google Analytics > Admin > Property Access Management > Add the service account email as Viewer
2. Get property ID — Google Analytics > Admin > Property Settings > copy the numeric Property ID (e.g. 518920216)

Step 3: Verify

Ask the user to restart Claude Code, then test with: "Show me my active users for the last 7 days"

Readiness states

Use explicit readiness states instead of a yes/no setup label:

missing_credentials -> credentials_present -> service_account_valid -> property_access_missing/property_id_invalid -> first_query_passed -> production_ready

If a query fails, report the failing state and the next fix. See references/readiness-and-secret-safety.md.

MCP vs direct API

Use MCP for local/manual analytics questions. For production client agents, scheduled reports, typed outputs, retries, quota handling, and multi-client isolation, prefer direct GA4 Data API scripts. See references/mcp-vs-direct-api.md.

If the MCP server fails to connect, check:

• Node.js 20+ is installed
• The private key includes the full [REDACTED PRIVATE KEY HEADER/FOOTER] wrapper and preserves newline formatting
• The service account email has Viewer access in GA4
• The property ID is numeric only (no properties/ prefix)

MCP Tool Reference

The actual deployed tool names on this workspace are namespaced. Map the bare names used in workflows below to the canonical calls:

When the workflows below reference runReport, the actual call is mcp__mcp-router__runReport. Same for the others. Use the qualified names.

Workflow

Follow these steps for every GA4 request.

Step 1: Parse the Request

Identify what the user wants and map it to the right workflow:

Determine the date range from the user's request. Use these conventions:

• "this month" = startDate: first day of current month, endDate: today
• "last week" = startDate: 7 days ago, endDate: yesterday
• "last 30 days" = startDate: 30daysAgo, endDate: today
• "last 3 months" = startDate: 90daysAgo, endDate: today
• If no date range is specified, default to the last 28 days

Step 2: Execute the Query

Workflow 1: Traffic Overview

When to use: User asks about overall traffic, sessions, users, or general performance trends.

Tool: runReport

Parameters:

• startDate / endDate: from the user's request
• dimensions: ["date"]
• metrics: ["activeUsers", "sessions", "screenPageViews", "bounceRate"]

Presentation: Show a summary of totals, then a trend table with key dates (weekly or daily depending on range length). Highlight any notable spikes or dips.

Workflow 2: Top Pages

When to use: User asks about best-performing pages, content analysis, or page-level metrics.

Tool: getPageViews with dimensions ["pagePath"], or runReport with dimensions ["pagePath", "pageTitle"] and metrics ["screenPageViews", "activeUsers", "bounceRate"].

Parameters:

• startDate / endDate: from the user's request
• dimensions: ["pagePath"] (add pageTitle if the user wants readable names)

Presentation: Ranked table of top pages. Default to top 10 unless the user specifies otherwise.

Workflow 3: Audience Analysis

When to use: User asks about who their visitors are — geography, devices, browsers, traffic sources.

Tool: runReport

Parameters:

• startDate / endDate: from the user's request
• dimensions: pick from ["country"], ["deviceCategory"], ["browser"], ["sessionSource", "sessionMedium"] based on what the user asks
• metrics: ["activeUsers", "sessions", "screenPageViews"]

Presentation: Ranked table by the primary dimension. For traffic sources, combine source/medium into a single column.

Workflow 4: Event Tracking

When to use: User asks about events, conversions, or specific user actions.

Tool: getEvents

Parameters:

• startDate / endDate: from the user's request
• eventName: if the user specifies a particular event, pass it here; otherwise omit to get all events

Presentation: Ranked list of events by count. Group standard GA4 events (pageview, sessionstart, first_visit, scroll, click) separately from custom events if both are present.

Workflow 5: User Behavior

When to use: User asks about engagement, bounce rate, session duration, or user quality metrics.

Tool: getUserBehavior

Parameters:

• startDate / endDate: from the user's request

Presentation: Key metrics summary with context (e.g., "Bounce rate of 45% is within the typical range for content sites"). Compare to previous period if the user asks for trend context.

Workflow 6: Conversion-Crater Detection

When to use: auditing a published article/page for CTA effectiveness; cross-referenced from the google-search-console skill's 28-Day Audit Loop.

Tool: mcp__mcp-router__runReport

Parameters:

• startDate / endDate: last 28 days
• dimensions: ["pagePath"]
• metrics: ["sessions", "eventCount"]
• dimensionFilter: filter pagePath to the article URL
• metricFilter (optional): filter eventName == "purchase" (or your site's primary conversion event)

Logic: if sessions ≥ 80 AND purchase event count == 0 over 28 days, flag as CTA audit required, not content audit.

Common causes (in order of frequency):

1. CTA uses a legacy CSS class with no styles → invisible button on live page
2. CTA points to wrong product for the article's audience (e.g., spoke article CTA → wrong bundle pack)
3. CTAs all stacked at end-only — users who bounce mid-article never see them
4. CTA copy is generic and doesn't match the article's promise (intent mismatch)

Output recommendation: pull the article body HTML, parse all CTA blocks with surrounding H2 context + estimated scroll position, propose class fix + product target correction. Re-measure 28 days after the fix lands.

Workflow 6: Organic Landing Pages / SEO Growth

When to use: User asks which SEO pages perform, which organic pages convert, page decay, content clusters, or organic channel quality.

Tool: runReport

Parameters:

• startDate / endDate: from the user's request
• dimensions: ["landingPagePlusQueryString", "sessionDefaultChannelGroup"]
• metrics: ["sessions", "activeUsers", "engagedSessions", "conversions", "totalRevenue"]
• filter: sessionDefaultChannelGroup == "Organic Search" when organic SEO analysis is requested

Presentation: Use templates/organic-landing-pages-report.md. Flag high-traffic/no-conversion pages, high-conversion/low-traffic pages, and decays vs previous period. See references/seo-growth-ga4-workflows.md.

Workflow 7: Ecommerce / Organic Revenue

When to use: Website has purchases, leads, subscriptions, bookings, or revenue-like conversion events.

Tool: runReport

Parameters:

• dimensions: ["landingPagePlusQueryString", "sessionDefaultChannelGroup"], then optionally ["eventName", "sessionDefaultChannelGroup"]
• metrics: ["sessions", "conversions", "totalRevenue", "eventCount"]
• filter Organic Search when analyzing SEO revenue

Presentation: Use templates/ecommerce-ga4-report.md. Report revenue/session and conversion rate only when revenue/conversion metrics are present. See references/ecommerce-revenue-workflows.md.

Workflow 8: GSC + GA4 Opportunity Join

When to use: The user wants SEO prioritization, query/page opportunities, or to connect search demand with post-click behavior.

Tools: GA4 runReport plus GSC data from a GSC skill/API/export.

Logic: join GSC page URLs to GA4 landingPagePlusQueryString by normalized page path.

Presentation: Use templates/gsc-ga4-join-report.md. Prioritize pages with high impressions + low CTR + conversions, high clicks + weak engagement, or low clicks + high conversion value. See references/gsc-ga4-join-workflow.md.

Workflow 9: Cron Monitoring and Experiment Follow-up

When to use: recurring client monitoring or measuring SEO actions after implementation.

Use templates/cron-monitoring-pack.md for daily organic traffic sentinels, weekly landing-page reviews, conversion quality reviews, ecommerce revenue reports, and 7/14/28/60/90-day experiment follow-ups.

Step 3: Analyze & Present

Use this output template:

## GA4 Report: [Report Type] — [Date Range]

### Key Findings
- [2-3 bullet points with the most important takeaways]

### [Report-Specific Section]
[Data tables, ranked lists, or trend summaries as appropriate]

| [Dimension] | [Metric 1] | [Metric 2] | ... |
|-------------|------------|------------|-----|
| ...         | ...        | ...        | ... |

### Recommendations
- [2-4 actionable insights based on the data]

### Notes
- Data source: Google Analytics 4
- Property ID: [from the MCP connection]
- Date range: [startDate] to [endDate]

Step 4: Handle Follow-ups

After presenting results, the user may ask:

• Drill down: "Break that down by device" — run a new query adding the dimension
• Compare periods: "Compare to last month" — run the same query for both periods and show a comparison
• Filter: "Only show organic traffic" — use dimensionFilter in runReport
• Join with GSC: normalize page paths before combining GSC pages with GA4 landing pages
• Export: "Give me this as a CSV" — format the data as CSV in a code block

Common Pitfalls

• Date format: Use YYYY-MM-DD (e.g., 2025-01-15) or relative strings like 7daysAgo, 30daysAgo, today, yesterday
• Property ID: Numeric only (e.g., 123456789). Do not include the properties/ prefix — this MCP server handles that internally
• Dimension/metric compatibility: Not all combinations work. If a query fails, simplify by removing dimensions or switching metrics. Common incompatible combo: totalRevenue with non-ecommerce properties
• Rate limits: The GA4 Data API has quotas. If you hit a rate limit, wait a moment and retry. Avoid running many back-to-back queries unnecessarily
• Sampling: Large date ranges or high-cardinality dimensions may return sampled data. Note this in your response if the API indicates sampling was applied
• Timezone: GA4 data uses the property's configured timezone, not the user's local timezone
• k-anonymity floor: demographic dimensions (age, gender, audience, country at low traffic) are suppressed when sample size falls below the privacy threshold. Don't pursue parent/age segmentation on properties with <1000 sessions per 28d — the data won't render.
• Attribution differences: GA4 session/channel attribution does not equal GSC click/query attribution. When joining GSC and GA4, explain the model difference.
• Revenue availability: totalRevenue can be zero because ecommerce is not configured, not because organic has no value. Verify tracking before conclusions.
• Conversions definition: conversions depends on which events are marked key events/conversions in GA4.
• Secret safety: never commit real .mcp.json, service-account JSON keys, .env, or private keys; use [REDACTED] examples.

Limitations

• Historical data: Only data that exists in the GA4 property is available. If the property was recently created, historical data may be limited.
• Real-time data: These tools query processed data, not real-time. There is typically a 24-48 hour delay for the most recent data.
• Custom dimensions/metrics: Only standard GA4 dimensions and metrics are documented here. Custom ones work but you need to know the exact API name.
• Data retention: GA4 free properties retain detailed data for 2 or 14 months (configurable). Aggregated data is available longer.
• No write access: This skill is read-only. It cannot create goals, modify property settings, or configure tracking.