Skip to main content
Glama
Walma-Labs

ga4-mcp

by Walma-Labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

run_realtime_report

Retrieve Google Analytics 4 realtime data from the last 30 minutes with dimensions, metrics, filters, and ordering.

Instructions

Runs a Google Analytics Data API realtime report covering roughly the last 30 minutes (https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-basics).

dimensions

Realtime dimensions (https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#dimensions), or user-scoped custom dimensions: from get_custom_dimensions_and_metrics, those whose apiName begins with "customUser:".

metrics

Realtime metrics only (https://developers.google.com/analytics/devguides/reporting/data/v1/realtime-api-schema#metrics). Realtime reports can't use custom metrics.

dimension_filter

Example dimension_filter arguments:

  1. A simple filter: {"filter":{"field_name":"eventName","string_filter":{"match_type":"BEGINS_WITH","value":"add"}}}

  2. A NOT filter: {"not_expression":{"filter":{"field_name":"eventName","string_filter":{"match_type":"BEGINS_WITH","value":"add"}}}}

  3. An empty value filter: {"filter":{"field_name":"source","empty_filter":{}}}

  4. An AND group filter: {"and_group":{"expressions":[{"filter":{"field_name":"sourceMedium","string_filter":{"match_type":"EXACT","value":"google / cpc"}}},{"filter":{"field_name":"eventName","in_list_filter":{"case_sensitive":true,"values":["first_visit","purchase","add_to_cart"]}}}]}}

  5. An OR group filter: {"or_group":{"expressions":[{"filter":{"field_name":"sourceMedium","string_filter":{"match_type":"EXACT","value":"google / cpc"}}},{"filter":{"field_name":"eventName","in_list_filter":{"case_sensitive":true,"values":["first_visit","purchase","add_to_cart"]}}}]}}

Notes: The API applies dimension_filter and metric_filter independently, so some combinations are impossible in one request, e.g. ((eventName = "page_view" AND eventCount > 100) OR (eventName = "join_group" AND eventCount < 50)). For conditions shaped ((D1 AND M1) OR (D2 AND M2)) either: a) run one report filtering on the supported subset (eventName in ["page_view","join_group"]) with eventCount included, and apply the metric conditions to the rows yourself; or b) run one report per (dimension condition, metric condition) pair. Prefer (a) — fewer reports — unless it would use excessive quota (https://developers.google.com/analytics/blog/2023/data-api-quota-management).

metric_filter

Example metric_filter arguments:

  1. A simple filter: {"filter":{"field_name":"eventCount","numeric_filter":{"operation":"GREATER_THAN","value":{"int64_value":"10"}}}}

  2. A NOT filter: {"not_expression":{"filter":{"field_name":"eventCount","numeric_filter":{"operation":"GREATER_THAN","value":{"int64_value":"10"}}}}}

  3. An empty value filter: {"filter":{"field_name":"purchaseRevenue","empty_filter":{}}}

  4. An AND group filter: {"and_group":{"expressions":[{"filter":{"field_name":"eventCount","numeric_filter":{"operation":"GREATER_THAN","value":{"int64_value":"10"}}}},{"filter":{"field_name":"purchaseRevenue","between_filter":{"from_value":{"double_value":10},"to_value":{"double_value":25}}}}]}}

  5. An OR group filter: {"or_group":{"expressions":[{"filter":{"field_name":"eventCount","numeric_filter":{"operation":"GREATER_THAN","value":{"int64_value":"10"}}}},{"filter":{"field_name":"purchaseRevenue","between_filter":{"from_value":{"double_value":10},"to_value":{"double_value":25}}}}]}}

Notes: The API applies dimension_filter and metric_filter independently, so some combinations are impossible in one request, e.g. ((eventName = "page_view" AND eventCount > 100) OR (eventName = "join_group" AND eventCount < 50)). For conditions shaped ((D1 AND M1) OR (D2 AND M2)) either: a) run one report filtering on the supported subset (eventName in ["page_view","join_group"]) with eventCount included, and apply the metric conditions to the rows yourself; or b) run one report per (dimension condition, metric condition) pair. Prefer (a) — fewer reports — unless it would use excessive quota (https://developers.google.com/analytics/blog/2023/data-api-quota-management).

order_bys

Example order_bys arguments:

  1. Ascending 'eventName': [ {"dimension":{"dimension_name":"eventName","order_type":"ALPHANUMERIC"},"desc":false} ]

  2. Descending 'campaignName', ignoring case: [ {"dimension":{"dimension_name":"campaignName","order_type":"CASE_INSENSITIVE_ALPHANUMERIC"},"desc":true} ]

  3. Ascending 'audienceId' (numeric): [ {"dimension":{"dimension_name":"audienceId","order_type":"NUMERIC"},"desc":false} ]

  4. Descending 'eventCount': [ {"metric":{"metric_name":"eventCount"},"desc":true} ]

  5. Ascending 'eventCount': [ {"metric":{"metric_name":"eventCount"},"desc":false} ]

  6. Dimension and metric combined: [ {"dimension":{"dimension_name":"eventName","order_type":"ALPHANUMERIC"},"desc":false}, {"metric":{"metric_name":"eventCount"},"desc":true} ]

  7. Several dimensions and metrics: [ {"dimension":{"dimension_name":"eventName","order_type":"ALPHANUMERIC"},"desc":false}, {"dimension":{"dimension_name":"audienceId","order_type":"NUMERIC"},"desc":false}, {"metric":{"metric_name":"eventCount"},"desc":true} ] The dimensions and metrics in order_bys must also be in the request's dimensions and metrics.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMax rows per response, 1-250000. Paginate with offset.
offsetNoRow count of the start row (first row is 0).
metricsYes
order_bysNoData API OrderBy objects; every field named must be in dimensions/metrics.
dimensionsYes
property_idYesThe Google Analytics property ID: a number, or 'properties/' followed by a number. Use get_account_summaries to find it.
metric_filterNoData API FilterExpression on metrics. Don't use it for dimensions; use dimension_filter.
dimension_filterNoData API FilterExpression on dimensions. Don't use it for metrics; use metric_filter.
return_property_quotaNoInclude the property's quota usage in the response.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does substantial work: it discloses the 30-minute window, mutual exclusivity of custom metrics, the independence of dimension_filter and metric_filter, and quota implications with a link. It stops short of describing response shape or pagination behavior, which matters for a tool with no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Headings front-load the important material and the examples are genuinely useful, but the Notes block under dimension_filter is reproduced verbatim under metric_filter, wasting roughly a third of the text. An agent must read past duplicated prose to reach order_bys.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter, nested-object tool with no output schema and no annotations, the description covers the hard parts (filter semantics, ordering rules, realtime restrictions). Remaining gaps are pagination and response format, both of which the schema only partially covers.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 78%, yet the description adds real meaning for the four complex parameters (dimensions, metrics, dimension_filter, metric_filter, order_bys) via five worked examples each and the constraint that order_bys fields must also appear in dimensions/metrics. It adds nothing for limit, offset, or return_property_quota, which the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Runs a Google Analytics Data API realtime report') plus the defining scope ('roughly the last 30 minutes'), which cleanly separates it from the sibling run_report (historical). An agent can pick it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational constraints: realtime dimensions only (plus 'customUser:' custom dimensions from get_custom_dimensions_and_metrics), realtime metrics only, and no custom metrics. It also explains how to handle impossible filter combinations and which workaround to prefer. It never explicitly contrasts with run_report, so the alternative-selection guidance is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools