Skip to main content
Glama
Walma-Labs

ga4-mcp

by Walma-Labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

run_report

Query Google Analytics 4 report data for sessions, users, page views, events, and revenue by property, date ranges, dimensions, metrics, filters, and order.

Instructions

Runs a Google Analytics Data API report (sessions, users, page views, events, revenue, and so on).

Rows come back flattened: one object per row keyed by dimension and metric name, metrics as numbers.

dimensions

Standard dimensions (https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions) available to every property, or the property's custom dimensions from get_custom_dimensions_and_metrics.

metrics

Standard metrics (https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics) available to every property, or the property's custom metrics from get_custom_dimensions_and_metrics.

date_ranges

Example date_ranges arguments:

  1. A single date range: [ {"start_date":"2025-01-01","end_date":"2025-01-31","name":"Jan2025"} ]

  2. A relative date range using 'yesterday' and 'today': [ {"start_date":"yesterday","end_date":"today","name":"YesterdayAndToday"} ]

  3. A relative date range using 'NdaysAgo': [ {"start_date":"30daysAgo","end_date":"yesterday","name":"Previous30Days"} ]

  4. Multiple date ranges (adds a 'dateRange' column to every row): [ {"start_date":"2025-01-01","end_date":"2025-01-31","name":"Jan2025"}, {"start_date":"2025-02-01","end_date":"2025-02-28","name":"Feb2025"} ]

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
date_rangesYesDate ranges: [{start_date, end_date, name?}]. Dates are YYYY-MM-DD, 'today', 'yesterday' or 'NdaysAgo'.
property_idYesThe Google Analytics property ID: a number, or 'properties/' followed by a number. Use get_account_summaries to find it.
currency_codeNoISO 4217, e.g. SEK. Defaults to the property's currency.
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

A3.9/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 well: it discloses the flattened row shape ('one object per row keyed by dimension and metric name, metrics as numbers'), the multi-date-range behavior (adds a 'dateRange' column), the independent-application quirk of the two filters, and a quota warning with a link. It does not state auth/permission requirements explicitly, though the read-only nature is strongly implied by 'runs a report'.

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?

Front-loaded with a one-line purpose and organized under headers, which is good. However, the identical multi-line 'Notes:' block about independent dimension_filter/metric_filter application is duplicated verbatim under both sections, wasting roughly ten lines, and the sheer length is disproportionate for routine calls.

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 an 11-parameter tool with no output schema, the description covers return shape, the complex filter/ordering/date semantics, quota implications, and pagination (via the schema's limit/offset). What is missing is comparatively minor: auth/permission expectations and any note on maximum result scaling beyond the quota link.

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

Parameters5/5

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

Schema coverage is already 82%, so the baseline would be 3, but the description goes well beyond the schema with concrete worked examples for the four hardest parameters (date_ranges, dimension_filter, metric_filter, order_bys), including relative dates, AND/OR/NOT groups, and numeric/between filters. It also warns that order_bys fields must also appear in dimensions/metrics.

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

Purpose4/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 report', with illustrative metrics (sessions, users, page views, events, revenue). It does not distinguish itself from the siblings run_realtime_report, run_funnel_report, or run_conversions_report, so an agent must infer that this is the general-purpose reporting tool.

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

Usage Guidelines3/5

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

There is no explicit routing guidance against the sibling report tools, only an implied 'general report' role. The description does give real operational guidance for a tricky case (that dimension_filter and metric_filter apply independently, with two workarounds and a preference for option (a) to conserve quota), which raises it above a bare 2.

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