Skip to main content
Glama
russjeffery

google-search-console-mcp

by russjeffery
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Hybrid

Query search performance data

query_search_analytics
Read-only

Retrieve clicks, impressions, CTR, and average position from Google Search Console to analyze search traffic and rankings. Group results by query, page, country, device, or date for targeted insights.

Instructions

Query clicks, impressions, CTR and average position from the Search Console Performance report - the core tool for all traffic and ranking analysis.

Group by one or more dimensions (query, page, country, device, searchAppearance, date, hour). Rows come back sorted by clicks descending, and only rows with data are returned. Omitting dimensions returns a single totals row for the whole property.

Behaviours worth planning around:

  • Data is final only up to about 3 days ago; use lastDays to get a safe window automatically.

  • Grouping by query triggers privacy filtering: rare queries are omitted entirely, so query-level clicks will not sum to the property total. Never present that gap as lost traffic.

  • Combining page and query is capped harder than either alone, so expect fewer rows than you might predict.

  • rowLimit maxes at 25000 per call; page with startRow for more.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
typeNoSearch surface. Defaults to "web". "discover" and "googleNews" support only a limited set of dimensions and have no query dimension at all.
endDateNoInclusive end date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set.
siteUrlNoSearch Console property, exactly as it appears in `list_sites`. URL-prefix properties include the scheme and a trailing slash ("https://example.com/"); domain properties use the "sc-domain:" prefix ("sc-domain:example.com"). These are distinct properties with different data.
lastDaysNoShorthand for a trailing window, e.g. 28 for "the last 28 days". The window ends 3 days ago because Search Console data is not final before then. Prefer this over startDate/endDate unless you need a specific window.
rowLimitNoRows to return, 1-25000. Defaults to 1000.
startRowNoZero-based offset for pagination. Defaults to 0.
dataStateNo"final" (default) returns only finalised data. "all" includes fresh, still-changing data for the most recent days. "hourly_all" is required when using the "hour" dimension.
startDateNoInclusive start date, YYYY-MM-DD, in Pacific Time. Ignored if lastDays is set.
dimensionsNoGroup results by these dimensions, in order. Omit for property-level totals. "date" gives a time series; "hour" requires dataState "hourly_all" and only covers roughly the last 10 days.
aggregationTypeNoHow to aggregate. Leave as "auto" unless you specifically need byPage or byProperty; changing it changes what a click counts as.
dimensionFilterGroupsNoFilter groups. Filters inside a group are ANDed together; supplying multiple groups is currently equivalent to one combined AND group in the API.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial behavioral detail beyond that: data finality lag, query-level privacy filtering, row limits, the cap on combining page and query, sorted output, and omission of empty rows. No contradiction exists between the description and annotations.

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?

The description is front-loaded with the core purpose, then gives grouping and return behavior, then uses a compact bulleted list for the most important planning caveats. Every sentence carries useful information and the structure makes the caveats scannable.

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 an 11-parameter tool with no output schema, the description covers the key behavioral gaps an agent needs before calling it: what is returned, how default totals work, data freshness, privacy filtering, expected row counts, and pagination. The remaining parameter details are already well documented in the input schema.

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 baseline is 3, but the description adds genuine meaning beyond the schema: sorting by clicks descending, only returning rows with data, the privacy-filtering effect of grouping by query, the harder cap when combining page and query, and pagination guidance for rowLimit/startRow. It does not cover every parameter, but the schema already does.

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 opens with a specific verb and resource: querying clicks, impressions, CTR, and average position from the Search Console Performance report. It also names the available dimensions and distinguishes its role as the core traffic and ranking analysis tool, making its purpose immediately identifiable relative to siblings.

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 description gives clear usage context: how to get totals, how to group, how to paginate, and why to use lastDays for a safe data window. It does not explicitly name alternatives like compare_search_analytics or state when not to use this tool, so it stops short of a full 5.

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