--- name: google-analytics description: "Query Google Analytics 4 data via MCP/direct workflows for traffic, organic landing pages, conversions, ecommerce revenue, page decay, user behavior, channel mix, GSC+GA4 joins, and recurring SEO growth monitoring. Trigger on: traffic analysis, analytics report, page performance, user engagement, conversion tracking, audience insights, organic revenue, SEO experiment follow-up." requires: mcp: [google-analytics] license: MIT --- # 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: ```text 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: ```json { "mcpServers": { "google-analytics": { "command": "npx", "args": ["-y", "mcp-server-google-analytics"], "env": { "GOOGLE_CLIENT_EMAIL": "", "GOOGLE_PRIVATE_KEY": "", "GA_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` 7. **Grant access in GA4** — Google Analytics > Admin > Property Access Management > Add the service account email as **Viewer** 8. **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: ```text 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: | Capability | Exact tool name | |---|---| | Page views (pagePath dimension) | `mcp__mcp-router__getPageViews` | | Active users (over date range) | `mcp__mcp-router__getActiveUsers` | | Events (by name or all) | `mcp__mcp-router__getEvents` | | Engagement / behavior metrics | `mcp__mcp-router__getUserBehavior` | | Custom multi-dimension reports | `mcp__mcp-router__runReport` | 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: | User Intent | Workflow | Primary Tool | |-------------|----------|-------------| | Traffic overview, trends over time, general stats | Traffic Overview | `runReport` | | Top pages, page performance, content analysis | Top Pages | `getPageViews` or `runReport` | | Audience breakdown by country, device, browser | Audience Analysis | `runReport` | | Event tracking, what events fire, event counts | Event Tracking | `getEvents` | | Bounce rate, session duration, engagement metrics | User Behavior | `getUserBehavior` | | Organic landing pages, page decay, cluster performance | SEO Growth GA4 | `runReport` | | Ecommerce / organic revenue / funnel events | Ecommerce Revenue | `runReport` | | GSC + GA4 opportunity join | GSC + GA4 Join | `runReport` + GSC data | 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 (page_view, session_start, 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.