io.github.surendranb/google-analytics-mcp

Check PyPI for newer versions of this MCP server and get upgrade instructions.

Return all dimensions in a specific category with their API names and descriptions. Returns: {"dimension_api_name": "description", ...} The category name must exactly match a value returned by list_dimension_categories. Use search_schema instead if you already have a keyword — it is faster and more targeted than browsing by category. Args: category: Exact category name from list_dimension_categories (case-insensitive).

Retrieve GA4 data with built-in intelligence for better and safer results. Returns on success: {"data": [...], "metadata": {...}, "_skills_tip": "..."}. For multi-row pulls (a time series like ['date'], or any breakdown) the result also carries "totals": {metric: value} — GA4 server-side aggregates across all rows. Read the period figure from "totals"; do NOT sum the rows yourself. (Additive metrics sum; rate metrics are period-computed by GA4.) Returns on volume warning: {"warning": "...", "estimated_rows": N, "suggestions": [...]} Returns on error: {"error": "..."} CRITICAL WORKFLOW — follow this sequence every time: 1. DISCOVER FIELDS: NEVER guess dimension or metric names. Call `search_schema`, `list_dimension_categories`, or `list_metric_categories` FIRST to verify exact API names for this property. Guessing costs you a failed round-trip. 2. DISCOVER PATTERN: For any domain-specific analysis, call `search_skills('<topic>')` BEFORE querying to get the proven methodology — correct dimensions, metrics, filters, and how to interpret the result. One extra call prevents multiple failures. Use for: traffic diagnosis, attribution, ecommerce, channel acquisition, content performance, geo/device segmentation, AI referrals, bot detection. 3. RETRIEVE: Call get_ga4_data with the verified fields and the skill's pattern. 4. TROUBLESHOOT: On schema error, invalid field, or filter parse error — do NOT retry by guessing. Your training may predate current GA4 (UA was sunset 2023-07-01). Call `search_schema('<keyword>')` to find the current name in THIS property, or `search_skills('ua-to-ga4' | 'common-metric-names' | 'filter-structures')` for the mapping. FIELD NAMES — GA4 API names vs common wrong guesses: - 'screenPageViews' not 'uniquePageviews' or 'pageViews' - 'totalUsers' not 'users' - 'keyEvents' not 'conversions' or 'goalCompletionsAll' - 'sessionKeyEventRate' not 'sessionConversionRate' or 'co…

Return all metrics in a specific category with their API names and descriptions. Returns: {"metric_api_name": "description", ...} The category name must exactly match a value returned by list_metric_categories. Use search_schema instead if you already have a keyword — it is faster and more targeted than browsing by category. Args: category: Exact category name from list_metric_categories (case-insensitive).

Returns the complete schema for the configured GA4 property, including all available dimensions and metrics (standard and custom). Warning: This can be a very large object (10k+ tokens). Use search_schema for most discovery tasks.

Returns the troubleshooting/setup guide for a topic, served from inside the server (no network needed). Use whenever you hit a schema error, dimension_filter parse error, IAM / 403 authorization error, or a boot-time setup error. Args: topic: One of "setup", "iam", or "schema".

List all dimension categories for this GA4 property, with a count of dimensions in each category. Returns: {"dimension_categories": {"Category Name": count, ...}} Use this as the first step in dimension exploration — browse categories, then call get_dimensions_by_category with the name that fits your analysis. Use search_schema instead if you already have a keyword to search for.

List all metric categories for this GA4 property, with a count of metrics in each category. Returns: {"metric_categories": {"Category Name": count, ...}} Use this as the first step in metric exploration — browse categories, then call get_metrics_by_category with the name that fits your analysis. Use search_schema instead if you already have a keyword to search for.

List all GA4 properties associated with an account.

Search for a keyword across all dimensions and metrics for this property. Returns a ranked list of up to 10 matching fields scored by relevance. Returns: {"top_results": {"DIMENSION: api_name": score, "METRIC: api_name": score, ...}} Use this when you have a concept ("engagement", "revenue", "channel") and need exact API field names before calling get_ga4_data. Use list_dimension_categories or list_metric_categories instead if you want to browse all available fields without a specific keyword. Args: keyword: One or more keywords to search for (e.g., "user", "campaign revenue").

Fetch analytical recipes and how-to guides from the GA4 skills library. Skills are domain-specific playbooks for common GA4 analysis patterns — exact dimensions, metrics, filters, and interpretation logic for each use case. Call this BEFORE querying get_ga4_data for any domain-specific analysis. Available skills: gcp-setup, traffic-diagnosis, attribution-scope, channel-acquisition, content-performance, geo-device-segmentation, ecommerce-analysis, ai-referral-analysis, bot-traffic-detection, common-metric-names, filter-structures, custom-dimensions, compatible-combinations, ua-to-ga4, date-ranges, ga4-limitations. Usage: - search_skills("") → returns full index of all skills - search_skills("gcp-setup") → returns the GCP service-account setup playbook - search_skills("ecommerce") → returns the ecommerce-analysis skill - search_skills("ua-to-ga4") → returns the UA→GA4 field name mapping Args: query: A skill name (exact slug) or empty string to browse the full index.

Interactively fix a broken GA4 MCP setup (missing property ID, missing or expired credentials, or missing GA4 access) by asking the user for the needed input through the client, then re-initializing without a restart. Call this whenever a configuration or authentication error is reported.