Google Analytics MCP Server

The GA4 MCP Server provides AI agents with specialized tools and skills to interact with Google Analytics 4 data. Key capabilities include:

• Analyze Traffic: Safely query specific dimension/metric pairs.
• Diagnose Drops: Analyze traffic decreases by breaking them down by channel, geography, or custom dimensions.
• Understand Schema: Look up definitions for metrics and identify allowed dimensions within your GA4 property.

GA4 allows you to access custom data using two distinct methods depending on whether the dimension is formally registered in the GA4 Admin settings:

1. Registered custom dimensions: Use the exact name returned by search_schema("custom").
2. Unregistered event parameters: If a parameter is sent by your tracking code but not registered as a dimension, access it inline using specific prefixes:
   • customEvent:parameter_name for event-scoped parameters.
   • customUser:property_name for user-scoped properties.

Note: The parameter_name must exactly match the name sent by your tracking code. If the property has not collected that specific parameter, the API will return an error.

// Example of unregistered event parameter access
customEvent:page_category

// Example of unregistered user property access
customUser:plan_type

To prevent query errors or invalid data in GA4 ecommerce analysis, avoid the following combinations:

• Item vs Session Scope: Do not combine itemId or itemSku with session-level metrics.
• Metric Conflict: Do not combine ecommercePurchases with eventCount in the same query.
• Best Practice: Always use separate queries for item-level analysis (e.g., product performance) and session-level analysis (e.g., channel performance).

All GA4 API names must use camelCase. Using snake_case (common in UA or other APIs) will result in errors.

| Wrong (snake_case) | Correct |
|---|---|
| `page_path` | `pagePath` |
| `session_source` | `sessionSource` |
| `device_category` | `deviceCategory` |
| `event_name` | `eventName` |
| `total_users` | `totalUsers` |

The ga4-analytics skill is designed for querying Google Analytics 4 (GA4) data. Use this skill when you need to retrieve information regarding:

• Traffic & Engagement: Active users, sessions, pageviews, or bounce rates.
• Acquisition: Channel acquisition, user acquisition numbers, or sessionSource.
• Breakdowns: Conversion breakdowns, device breakdowns, or geographical traffic reports (e.g., using the country dimension).
• Custom Data: Custom dimensions defined in your GA4 property.

The server includes built-in analytical recipes (skills) that load dynamically from GitHub to guide AI agents through specific tasks. You can discover these using skills_list, search for them with search_skills, and load their procedural steps using skill_read.

Available playbooks include:

• traffic-diagnosis: Root cause analysis for traffic drops.
• channel-acquisition: Channel grouping and attribution modeling.
• ecommerce-analysis: Revenue and conversion funnel analysis.
• ai-referral-analysis: Tracking referral traffic from AI models like ChatGPT, Claude, Perplexity, and Gemini.

When diagnosing traffic, avoid these common mistakes:

• Do not conclude "traffic dropped" from a single metric in isolation. Always look at the relationship between volume and engagement.
• Do not compare to the prior week without accounting for day-of-week patterns. For example, comparing a Monday to a Sunday is invalid. Always compare Monday-to-Monday or use full-week comparisons to account for seasonality and weekly patterns.
• Bot detection: If you suspect a bot flood, look for engagementRate near 0, averageSessionDuration ≈ 0, or unusual hostname/country concentrations (refer to the bot-traffic-detection skill).

GA4 does not support MAU, WAU, or DAU as direct metric names. Instead, use rolling n-day metrics which count distinct users active in the N days ending on that date:

• DAU (Daily Active Users): Use active1DayUsers.
• WAU (Weekly Active Users): Use active7DayUsers.
• MAU (Monthly Active Users): Use active28DayUsers.
• Total distinct users in range: Use activeUsers.

Warning on Aggregation: Never sum daily activeUsers across rows to calculate a period total, as this double-counts users active on multiple days. To get a total for a period, query activeUsers once over the entire date range without a date dimension, or use active28DayUsers for a rolling month.

Stickiness ratios like dauPerMau, dauPerWau, and wauPerMau are also available.

A common error is using snake_case (the standard for many other APIs). All GA4 API names must use camelCase.

| Wrong (snake_case) | Correct |
|---|---|
| `page_path` | `pagePath` |
| `session_source` | `sessionSource` |
| `device_category` | `deviceCategory` |
| `event_name` | `eventName` |
| `total_users` | `totalUsers` |

GA4 enforces strict rules regarding which dimensions and metrics can be requested together. Errors occur when you mix dimensions and metrics from incompatible scopes. GA4 data is categorized into three primary scopes:

• Event Scope: Relates to individual actions. Examples: eventName, customEvent:* (dimensions) and eventCount (metric).
• Session Scope: Relates to a user's visit. Examples: sessionDefaultChannelGroup, sessionSource, sessionCampaignName (dimensions) and sessions, bounceRate, sessionKeyEventRate (metrics).
• User Scope: Relates to the user's identity/history. Examples: firstUserDefaultChannelGroup, firstUserSource (dimensions) and totalUsers, newUsers (metrics).