Skip to main content
Glama
@mgcrea/mcp-google-search-console

@mgcrea/mcp-google-search-console

by mgcrea

Search Console: Query Search Analytics

gsc_query_search_analytics
Read-only

Fetch Search Console clicks, impressions, CTR and average position grouped by query, page, date, country or device to analyze search performance, with filters and row paging.

Instructions

Search performance for a property: clicks, impressions, CTR and average position, grouped by the dimensions you pick (date, hour, query, page, country, device, searchAppearance, brandedClassification). Rows come back with named fields ({query, page, clicks, impressions, ctr, position}), sorted by clicks (by date when grouped by date), plus returned_totals: the sum of the RETURNED rows only, not the property total (rows past row_limit are not counted, and query-grouped rows omit anonymized queries); and next_start_row when there may be more. Dates are Pacific-time calendar days; data lags 2-3 days and is kept 16 months; the default range is the 28 days ending 3 days ago. QUOTA: grouping or filtering by page or query, and long ranges, are the expensive part of the 10-minute and daily load quotas — ask for the dimensions you need, not all of them. The hour dimension needs data_state hourly_all (set for you) and covers only about the last 10 days, which is then the default range. To find what changed between two periods use gsc_compare_periods instead of two queries.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "site": "<site>"
    },
    "name": "gsc_query_search_analytics"
  }
}

Input Schema

NameRequiredDescriptionDefault
siteYesThe Search Console property, e.g. "sc-domain:example.com" (a domain property: every protocol and subdomain) or "https://www.example.com/" (a URL-prefix property: exactly that scheme, host and path). A bare "example.com" or a URL without its trailing slash is resolved against the properties this account can see, preferring the domain property; the response's `site` says which property was read. gsc_list_sites lists them.
typeNoWhich Google surface: web (default, Search's main results), image, video, news (the News tab in Search), discover, googleNews (news.google.com and the News app), webMultimodal (Lens, Circle to Search, image uploads). discover and googleNews have no query dimension and no position.web
filtersNoFilters, all AND-ed together, e.g. [{"dimension":"page","operator":"contains","expression":"/blog/"}]. Filtering by page or query costs as much load quota as grouping by it.
end_dateNoLast day, YYYY-MM-DD, inclusive, a calendar day in Pacific time (America/Los_Angeles) — Search Console's own day boundary, not UTC.
row_limitNoRows to return (1-25000). Defaults to 100. Every row lands in the conversation, so raise it deliberately; page with start_row instead of asking for thousands.
start_rowNoZero-based row offset, for paging: pass the previous response's next_start_row.
data_stateNofinal (Google's default): finalized data only. all: include the fresh, still-changing last days. hourly_all: required by, and set automatically for, the hour dimension.
dimensionsNoGroup by these, in this order, e.g. ["query"] or ["page","device"]. Empty (the default) returns one row of property totals. Each row carries a named field per dimension. brandedClassification (BRANDED/NON_BRANDED) has data from 2026-02-21 on, only for properties with enough volume.
start_dateNoFirst day, YYYY-MM-DD, inclusive, a calendar day in Pacific time (America/Los_Angeles) — Search Console's own day boundary, not UTC.
aggregationNoHow results are aggregated. auto (Google's default) is by page when grouping or filtering by page, by property otherwise; byProperty cannot be used with page.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

The annotations only declare readOnlyHint and openWorldHint, while the description adds substantial behavioral context: Pacific-time calendar days, 2-3 day data lag, 16-month retention, a default 28-day range, returned_totals semantics that exclude rows past row_limit and anonymized queries, next_start_row pagination, and the quota cost drivers. This is well beyond what the annotations provide and does not contradict them.

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

Conciseness4/5

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

The description is dense and front-loads what the tool returns before moving into caveats, quota, and pagination. Every sentence carries useful information, though the semicolon-heavy single paragraph reduces scanability; the length is justified by the tool's complexity but could be structured more cleanly.

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

Completeness5/5

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

There is no output schema, so the description must explain return values, and it does: named fields, returned_totals semantics, and next_start_row for pagination. It also covers date boundaries, data lag, retention, default range, and quota costs, making it complete for a 10-parameter analytics query tool.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds useful context such as the default date range and quota implications of page/query grouping, but most parameter-level semantics (formats, enums, defaults, and filtering rules) are already fully documented in the schema.

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?

The description states a specific verb and resource: it returns Search performance metrics (clicks, impressions, CTR, average position) for a property, grouped by the requested dimensions. It also names the concrete row fields and explicitly routes period comparisons to gsc_compare_periods, so an agent can distinguish it from siblings.

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

Usage Guidelines5/5

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

It gives explicit guidance on when to use this tool and what to avoid: ask only for needed dimensions, note that page/query grouping or filtering consumes quota, use gsc_compare_periods for period comparisons instead of two separate queries, and account for the special hour-dimension constraints. These are concrete alternatives and exclusions, not implied usage.

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