Skip to main content
Glama
AKzar1el

Google Search Console MCP

by AKzar1el
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Query search analytics

analytics.query
Read-only

Query Google Search Console search analytics to get clicks, impressions, CTR, and position, grouped by dimension or as site totals. Supports filters, pagination, and multiple search types.

Instructions

Query Google Search Console search analytics data. Returns { row_count, start_row, rows } where each row has keys (dimension values), clicks, impressions, ctr, and position. When row_count equals row_limit, the response includes next_start_row — pass it back as start_row to fetch the next page. When Google provides them, response_aggregation_type and metadata are also included; metadata may identify the first incomplete date or hour.

IMPORTANT BEHAVIORS — read before calling:

  • For SITE TOTALS (total impressions, total clicks, overall CTR, overall average position), call with dimensions: []. This returns a single row containing the true site-level totals. Do NOT call with dimensions: ["query"] and sum the rows — Google omits anonymized low-volume queries from per-dimension responses, so summing per-query rows will undercount.

  • For TOP QUERIES / PAGES / COUNTRIES / DEVICES, call with the matching dimension. Expect the returned rows to cover only a subset of total impressions; this is normal Google behavior, not a data error.

  • DATA FRESHNESS: Search Console data lags about 2-3 days behind real time. If the user asks about "today" or "yesterday", expect empty or partial rows for the most recent days; the latest reliably-complete date is usually 3 days ago.

  • AVERAGE POSITION is impression-weighted. To compute an overall position across multiple rows, use sum(position * impressions) / sum(impressions). Never plain-average the position column across rows.

  • CTR in the response is a 0–1 fraction. Multiply by 100 for percent.

  • Use search_type to query image/video/news/discover indexes separately from web.

  • Use dimension_filter_groups to filter by country, device, query content, page URL, or search feature. includingRegex and excludingRegex use RE2 syntax. For brand vs non-brand splits, pass a single regex filter on the 'query' dimension.

  • data_state defaults to 'all' which matches the GSC dashboard. Pass 'final' only when the user explicitly asks for stable, non-preliminary data.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
end_dateYesEnd date (inclusive) in YYYY-MM-DD format. Note the 2-3 day data lag: the most recent complete date is usually 3 days ago.
site_urlYesThe Search Console property identifier, exactly as returned by sites.list. Two formats exist: domain properties use 'sc-domain:example.com'; URL-prefix properties use the full URL including protocol and trailing slash, e.g. 'https://www.example.com/'. Passing the wrong format returns a permission error even when the user owns the site — call sites.list first if unsure.
row_limitNoMaximum rows to return (1-25000). Defaults to 100, which is plenty for most questions; raise it only for bulk exports and page through with start_row.
start_rowNoZero-based row offset for pagination. When a response contains next_start_row, pass it here to fetch the next page.
data_stateNo'all' includes fresh (preliminary) data and matches the GSC dashboard; 'final' returns only finalized data.all
dimensionsNoDimensions to group rows by. Pass [] (empty array) to get a single row of true site-level totals.
start_dateYesStart date (inclusive) in YYYY-MM-DD format.
search_typeNoWhich search index to query. Defaults to web.web
aggregation_typeNoHow Google aggregates metrics. Leave as 'auto' unless you specifically need byPage or byProperty semantics.auto
dimension_filter_groupsNoOptional filters ANDed together, e.g. [{ groupType: 'and', filters: [{ dimension: 'country', operator: 'equals', expression: 'usa' }] }]. Countries use ISO 3166-1 alpha-3 codes.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
rowsYes
metadataNoGoogle data-completeness metadata, included only when returned by Google.
row_countYes
start_rowYes
next_start_rowNo
response_aggregation_typeNoGoogle response aggregation type, included only when returned by Google.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already signal read-only and open-world behavior, and the description adds substantial context: 2-3 day data lag, anonymized low-volume queries being omitted, impression-weighted average position, CTR as a 0-1 fraction, and pagination via next_start_row. This is unusually transparent and leaves little to guess about response behavior.

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

Conciseness5/5

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

Although long, the description is front-loaded with purpose and return shape, then organized into a clearly labeled 'IMPORTANT BEHAVIORS' section with focused bullets. Every sentence carries operational meaning, and the length is justified by the tool's 10-parameter complexity.

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?

For a complex tool with 10 parameters, the description covers return structure, pagination, data freshness, aggregation semantics, filter usage, and data_state behavior. This is sufficient for an agent to select correct parameter values and interpret results reliably; no significant operational gap remains.

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 100%, so the parameters are already well documented and the baseline is 3. The description adds valuable interpretation beyond the schema, such as RE2 syntax for regex filters, brand vs non-brand filter strategy, and the warning that summing per-query rows undercounts totals, which raises it to 4.

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 opening sentence names a specific verb and resource: querying Google Search Console search analytics data, then defines the return envelope and row fields. This makes the tool's function unmistakable and enough to distinguish it from sibling analytics tools even without an explicit contrast.

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?

The 'IMPORTANT BEHAVIORS' section gives explicit when-to/when-not guidance: use dimensions: [] for site totals, do not sum per-query rows, use matching dimensions for top queries, and pass 'final' only when stable data is requested. It does not explicitly route the agent to sibling tools such as analytics.compare, so it stops short of a full alternative-selection explanation.

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