Skip to main content
Glama
noviq-ai

Google Analytics MCP Server

by noviq-ai
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

run_report

Generate a tailored Google Analytics report by specifying property, date range, dimensions, metrics, and optional filters or sorting to answer specific questions about user behavior and site performance.

Instructions

      Runs a Google Analytics Data API report.

Note that the reference docs at https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta all use camelCase field names, but field names passed to this method should be in snake_case since the tool is using the protocol buffers (protobuf) format. The protocol buffers for the Data API are available at https://github.com/googleapis/googleapis/tree/master/google/analytics/data/v1beta.

Args: property_id: The Google Analytics property ID. Accepted formats are: - A number - A string consisting of 'properties/' followed by a number date_ranges: A list of date ranges (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/DateRange) to include in the report. dimensions: A list of dimensions to include in the report. metrics: A list of metrics to include in the report. dimension_filter: A Data API FilterExpression (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/FilterExpression) to apply to the dimensions. Don't use this for filtering metrics. Use metric_filter instead. The field_name in a dimension_filter must be a dimension, as defined in the get_standard_dimensions and get_dimensions tools. metric_filter: A Data API FilterExpression (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/FilterExpression) to apply to the metrics. Don't use this for filtering dimensions. Use dimension_filter instead. The field_name in a metric_filter must be a metric, as defined in the get_standard_metrics and get_metrics tools. order_bys: A list of Data API OrderBy (https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/OrderBy) objects to apply to the dimensions and metrics. limit: The maximum number of rows to return in each response. Value must be a positive integer <= 250,000. Used to paginate through large reports, following the guide at https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination. offset: The row count of the start row. The first row is counted as row 0. Used to paginate through large reports, following the guide at https://developers.google.com/analytics/devguides/reporting/data/v1/basics#pagination. currency_code: The currency code to use for currency values. Must be in ISO4217 format, such as "AED", "USD", "JPY". If the field is empty, the report uses the property's default currency. return_property_quota: Whether to return property quota in the response.

      ## Hints for arguments

      Here are some hints that outline the expected format and requirements
      for arguments.

      ### Hints for `dimensions`

      The `dimensions` list must consist solely of either of the following:

      1.  Standard dimensions defined in the HTML table at
          https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions.
          These dimensions are available to *every* property.
      2.  Custom dimensions for the `property_id`. Use the
          `get_custom_dimensions_and_metrics` tool to retrieve the list of
          custom dimensions for a property.

      ### Hints for `metrics`

      The `metrics` list must consist solely of either of the following:

      1.  Standard metrics defined in the HTML table at
          https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics.
          These metrics are available to *every* property.
      2.  Custom metrics for the `property_id`. Use the
          `get_custom_dimensions_and_metrics` tool to retrieve the list of
          custom metrics for a property.


      ### Hints for `date_ranges`:
      Example date_range 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' and 'today':
    [ {"start_date": "30daysAgo", "end_date": "yesterday", "name": "Previous30Days"}]

  4. Multiple date ranges:
    [ {"start_date": "2025-01-01", "end_date": "2025-01-31", "name": "Jan2025"}, {"start_date": "2025-02-01", "end_date": "2025-02-28", "name": "Feb2025"} ]


      ### Hints for `dimension_filter`:
      Example dimension_filter arguments:
  1. A simple filter:
    {"filter": {"field_name": "eventName", "string_filter": {"match_type": 2, "value": "add", "case_sensitive": false}}}

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

  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": 1, "value": "google / cpc", "case_sensitive": false}}}, {"filter": {"field_name": "eventName", "in_list_filter": {"values": ["first_visit", "purchase", "add_to_cart"], "case_sensitive": true}}}]}}

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

Notes: The API applies the dimension_filter and metric_filter independently. As a result, some complex combinations of dimension and metric filters are not possible in a single report request.

For example, you can't create a `dimension_filter` and `metric_filter`
combination for the following condition:

(
  (eventName = "page_view" AND eventCount > 100)
  OR
  (eventName = "join_group" AND eventCount < 50)
)

This isn't possible because there's no way to apply the condition
"eventCount > 100" only to the data with eventName of "page_view", and
the condition "eventCount < 50" only to the data with eventName of
"join_group".

More generally, you can't define a `dimension_filter` and `metric_filter`
for:

(
  ((dimension condition D1) AND (metric condition M1))
  OR
  ((dimension condition D2) AND (metric condition M2))
)

If you have complex conditions like this, either:

a)  Run a single report that applies a subset of the conditions that
    the API supports as well as the data needed to perform filtering of the
    API response on the client side. For example, for the condition:
    (
      (eventName = "page_view" AND eventCount > 100)
      OR
      (eventName = "join_group" AND eventCount < 50)
    )
    You could run a report that filters only on:
    eventName one of "page_view" or "join_group"
    and include the eventCount metric, then filter the API response on the
    client side to apply the different metric filters for the different
    events.

or

b)  Run a separate report for each combination of dimension condition and
    metric condition. For the example above, you'd run one report for the
    combination of (D1 AND M1), and another report for the combination of
    (D2 AND M2).

Try to run fewer reports (option a) if possible. However, if running
fewer reports results in excessive quota usage for the API, use option
b. More information on quota usage is at
https://developers.google.com/analytics/blog/2023/data-api-quota-management.


      ### Hints for `metric_filter`:
      Example metric_filter arguments:
  1. A simple filter:
    {"filter": {"field_name": "eventCount", "numeric_filter": {"operation": 4, "value": {"int64_value": "10"}}}}

  2. A NOT filter:
    {"not_expression": {"filter": {"field_name": "eventCount", "numeric_filter": {"operation": 4, "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": 4, "value": {"int64_value": "10"}}}}, {"filter": {"field_name": "purchaseRevenue", "between_filter": {"from_value": {"double_value": 10.0}, "to_value": {"double_value": 25.0}}}}]}}

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

Notes: The API applies the dimension_filter and metric_filter independently. As a result, some complex combinations of dimension and metric filters are not possible in a single report request.

For example, you can't create a `dimension_filter` and `metric_filter`
combination for the following condition:

(
  (eventName = "page_view" AND eventCount > 100)
  OR
  (eventName = "join_group" AND eventCount < 50)
)

This isn't possible because there's no way to apply the condition
"eventCount > 100" only to the data with eventName of "page_view", and
the condition "eventCount < 50" only to the data with eventName of
"join_group".

More generally, you can't define a `dimension_filter` and `metric_filter`
for:

(
  ((dimension condition D1) AND (metric condition M1))
  OR
  ((dimension condition D2) AND (metric condition M2))
)

If you have complex conditions like this, either:

a)  Run a single report that applies a subset of the conditions that
    the API supports as well as the data needed to perform filtering of the
    API response on the client side. For example, for the condition:
    (
      (eventName = "page_view" AND eventCount > 100)
      OR
      (eventName = "join_group" AND eventCount < 50)
    )
    You could run a report that filters only on:
    eventName one of "page_view" or "join_group"
    and include the eventCount metric, then filter the API response on the
    client side to apply the different metric filters for the different
    events.

or

b)  Run a separate report for each combination of dimension condition and
    metric condition. For the example above, you'd run one report for the
    combination of (D1 AND M1), and another report for the combination of
    (D2 AND M2).

Try to run fewer reports (option a) if possible. However, if running
fewer reports results in excessive quota usage for the API, use option
b. More information on quota usage is at
https://developers.google.com/analytics/blog/2023/data-api-quota-management.


      ### Hints for `order_bys`:
      Example order_bys arguments:

1.  Order by ascending 'eventName':
    [ {"dimension": {"dimension_name": "eventName", "order_type": 1}, "desc": false} ]

2.  Order by descending 'eventName', ignoring case:
    [ {"dimension": {"dimension_name": "campaignName", "order_type": 2}, "desc": true} ]

3.  Order by ascending 'audienceId':
    [ {"dimension": {"dimension_name": "audienceId", "order_type": 3}, "desc": false} ]

4.  Order by descending 'eventCount':
    [ {"metric": {"metric_name": "eventValue"}, "desc": true} ]

5.  Order by ascending 'eventCount':
    [ {"metric": {"metric_name": "eventCount"}, "desc": false} ]

6.  Combination of dimension and metric order bys:
    [
      {"dimension": {"dimension_name": "eventName", "order_type": 1}, "desc": false},
      {"metric": {"metric_name": "eventValue"}, "desc": true},
    ]

7.  Order by multiple dimensions and metrics:
    [
      {"dimension": {"dimension_name": "eventName", "order_type": 1}, "desc": false},
      {"dimension": {"dimension_name": "audienceId", "order_type": 3}, "desc": false},
      {"metric": {"metric_name": "eventValue"}, "desc": true},
    ]

The dimensions and metrics in order_bys must also be present in the report
request's "dimensions" and "metrics" arguments, respectively.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
property_idYes
date_rangesYes
dimensionsYes
metricsYes
dimension_filterNo
metric_filterNo
order_bysNo
limitNo
offsetNo
currency_codeNo
return_property_quotaNo

Tool Definition Quality

B3.4/5.0
Behavior3/5

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

The description extensively covers parameter behavior, especially filter independence and limitations, and includes notes on pagination and snake_case naming. However, it lacks information on response structure, error handling, and authentication, leaving gaps for a tool with no annotations.

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?

The description is well-structured with headings and examples, but it is overly long and repetitive (e.g., filter notes repeated twice). Conciseness is compromised despite good organization.

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

Completeness3/5

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

The description thoroughly covers parameter usage and filter limitations, but does not describe the response format or provide usage context relative to sibling tools. Missing output schema information further reduces completeness.

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?

With 0% schema coverage, the description compensates exceptionally well by providing detailed hints, examples, and links for each parameter including date_ranges, filters, order_bys, and more. This adds significant meaning beyond the bare schema types.

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?

The description clearly states it runs a Google Analytics Data API report, specifying the primary function. However, it does not explicitly distinguish from the sibling tool 'run_realtime_report', relying on the name difference alone.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus the sibling 'run_realtime_report' or other alternatives. The description focuses on parameter details rather than use case differentiation.

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

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/noviq-ai/google-analytics-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server