This server is a read-only MCP bridge to Google Search Console, letting AI agents inspect properties, traffic analytics, sitemaps, and page indexing under their own service-account credentials.
List all Search Console properties accessible to the service account, with permission level.
Query Search Analytics for clicks, impressions, CTR, and position, with dimensions (date, query, page, country, device, search appearance, hour), search types, filters, filter groups, aggregation, date ranges, and auto-pagination up to 1M rows.
Fetch list of sitemaps for a property, filter by index, or get a single sitemap by feedpath.
Inspect a single URL's Google index status, coverage, canonical, AMP, and rich results.
Batch-inspect many URLs with client-side rate limiting (default 8 req/s) and per-URL error handling.
Configure via environment: service-account credentials, log level, retry backoff, API base overrides, and test token.
Provides read-only access to Google Search Console, allowing listing of properties, querying Search Analytics with filters and pagination, listing sitemaps, and inspecting URL index status, including batch inspection with throttling.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.scalably/gsc-mcp show me top queries and clicks for last 28 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Read-only MCP server for Google Search Console. Five tools cover the read surface: properties, Search Analytics (filters, auto-pagination past the 25,000-row cap, hourly data), sitemaps, URL inspection, batch inspection with throttling. We run this server in production for every SEO client.
Claude Code:
claude mcp add gsc -e GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json -- uvx scalably-gsc-mcpCodex:
codex mcp add gsc --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json -- uvx scalably-gsc-mcpClaude Desktop: download gsc-mcp.mcpb from the latest GitHub release and open it.
Related MCP server: gsc-mcp
In Google Cloud, create or pick a project and enable the Google Search Console API on it (APIs and Services, Library).
Create a service account in that project and download its JSON key.
Add the service account's email as a user on each Search Console property you want to query (Settings, Users and permissions). Full or restricted permission both work for reading.
No OAuth consent screen is needed; the server authenticates as the service account with the webmasters.readonly scope.
Tool | What it does |
| List the Search Console properties the service account can read |
| Query Search Analytics with filters, auto-pagination and hourly data |
| List sitemaps for a property or read one sitemap |
| Inspect one URL's index status |
| Inspect many URLs with client-side throttling |
Variable | Required | Purpose |
| yes | Path to a Google service-account JSON file with the Search Console read-only scope; share each property with the service account email |
| no | INFO (default) or DEBUG |
| no | Base delay in seconds for the retry backoff on transient API errors (default 1) |
| no | Override the two Google API base URLs (used by the test suite to point at a local fake; leave unset in normal use) |
| no | Test-suite only: a literal bearer token that bypasses the service account. Never set it in normal use |
Every tool returns JSON with status (succeeded, partial, no_op), operation, summary, target, result, proof, warnings, recovery. Failures surface as a tool error whose text is <code>: <message> <hint>. A partial status with proof.nextStartRow means: continue from that row.
25,000 rows per Search Analytics call (the server auto-paginates past it up to max_rows). URL inspection: Google allows 600 per minute and 2,000 per day per property. The server paces batch inspection client-side (default 8 requests per second) and warns when a batch exceeds the daily quota; it does not track daily usage across calls, so keep your own count.
Each release lists the package version, the .mcpb sha256 and the production commit it was derived from in CHANGELOG.md. CI runs the tests and a clean install of the built wheel on every push.
This server runs locally, on your machine, under your own credentials. It collects no personal data, contains no telemetry, stores nothing persistently, and talks only to the vendor API it wraps. No third party, including Scalably, receives your data. Contact: hello@scalably.io. Canonical copy: https://scalably.io/connector-privacy.html
MIT. Copyright Scalably.
Inspect many URLs under a single Search Console property. Rate-limited.
Respects Google's 600 QPM / 2,000 QPD per-site limits. Default pace of 8 QPS stays well under 600/minute with headroom. For large jobs (>2000 URLs), split across days or across multiple verified properties (e.g. per-subdomain).
Args: urls: list of fully-qualified URLs under site_url. No dedup. site_url: the Search Console property. language_code: BCP-47, default "en-US". requests_per_second: pace. Max ~10 (600 QPM). Caller can lower on 429 pressure. continue_on_error: if True, collect per-URL errors instead of aborting.
Returns: { "results": [{"url": str, "inspection": {...flattened...}} | {"url": str, "error": str}], "count": total, "errors": N, "skipped": 0 }
Quota warning: This does NOT replace the Search Analytics API for bulk query analysis. If the intent is "which pages have most traffic", use gsc_query_search_analytics instead - 40,000 QPM per project vs 600/site here.
| Name | Required | Description | Default |
|---|---|---|---|
| urls | Yes | ||
| site_url | Yes | ||
| language_code | No | en-US | |
| continue_on_error | No | ||
| requests_per_second | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses concrete rate limits, the default 8 QPS pace, the ~10 QPS maximum, behavior under 429 pressure, and the lack of deduplication. It also clarifies continue_on_error behavior, making the tool's runtime behavior fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with an opening summary, rate-limit context, an Args section, a Returns section, and a quota warning. Every sentence adds operational value, and the most important scoping information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter rate-limited batch tool with no schema descriptions, the description covers invocation, parameter semantics, error handling, rate limits, return shape, and alternative routing. Nothing essential for an agent to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description richly documents each parameter: fully-qualified URLs under site_url, the Search Console property, BCP-47 language_code, rate limit semantics for requests_per_second, and the conditional effect of continue_on_error. This fully compensates for the schema's lack of descriptive text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Inspect many URLs under a single Search Console property', stating a specific verb, resource, and batch scope. The batch nature clearly differentiates it from the sibling gsc_inspect_url, and the quota warning distinguishes it from gsc_query_search_analytics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when not to use this tool: it explicitly names gsc_query_search_analytics as the alternative for bulk traffic analysis. It also provides practical usage guidance for large jobs, including splitting across days or multiple verified properties, and mentions lowering requests_per_second when hitting 429 pressure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a URL in the Google index. Flattened response.
Checks index status, coverage state, canonical URLs, crawl info, AMP status, and rich results. Does NOT trigger a live crawl - checks Google's current index snapshot only.
Args: inspection_url: fully-qualified URL to inspect (must be under the property). site_url: the Search Console property - "https://example.com/" or "sc-domain:example.com". language_code: IETF BCP-47, default "en-US".
Quota: 2,000 requests/day/site + 600 requests/minute/site. Requires the SA to be a Full user on the property (Restricted users get 403 here).
Returns a flat dict with top-level verdict, coverage_state, canonical info,
plus optional amp and rich_results sub-objects. _raw has the full
untouched payload.
| Name | Required | Description | Default |
|---|---|---|---|
| site_url | Yes | ||
| language_code | No | en-US | |
| inspection_url | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, but the description adds valuable behavioral context: no live crawl, quota limits (2,000/day/site + 600/min), and permission requirements. It also discloses the flattened response shape and the `_raw` field, going well beyond what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections: one-line purpose, capability list, behavioral warning, args, quota/auth, and return shape. Information is front-loaded and every section carries necessary information; the only minor redundancy is 'Flattened response' appearing in both the first line and the returns section.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All essential invocation context is present: purpose, parameter semantics, quota, permissions, non-live-crawl behavior, and return structure. With an output schema also available, nothing critical is missing for an agent to call and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully documents each parameter: inspection_url must be fully-qualified and under the property, site_url formats are given ('https://example.com/' or 'sc-domain:example.com'), and language_code is described as IETF BCP-47 with default 'en-US'. This completely compensates for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Inspect a URL in the Google index,' and enumerates the concrete checks (index status, coverage, canonical, crawl info, AMP, rich results). The description is unambiguous about what the tool does, though it does not explicitly compare itself to the sibling gsc_batch_inspect_urls, so its sibling differentiation is implied rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear use context: it operates on Google's current index snapshot and explicitly warns it does not trigger a live crawl, which helps an agent decide when a live fetch tool would be needed. It also gives auth prerequisites (Full user, Restricted users get 403) and quota numbers. However, it does not explicitly state when to choose this single-URL tool over gsc_batch_inspect_urls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sitemaps on a site - or fetch one sitemap by feedpath.
Args: site_url: the Search Console property. sitemap_index: optional - if set, list only the children of a sitemap-index URL (e.g. "https://example.com/sitemap_index.xml"). feedpath: optional - if set, returns the single sitemap entry at that URL instead of the list (absorbs the prior get_sitemap tool).
Returns: {"sitemaps": [...], "count": N} or {"sitemap": {...}} if feedpath given. Each entry: {path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type, warnings, errors, contents}.
| Name | Required | Description | Default |
|---|---|---|---|
| feedpath | No | ||
| site_url | Yes | ||
| sitemap_index | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly and openWorld, and the description adds meaningful behavior: feedpath changes the response shape from a list to a single object, sitemap_index filters results, and each entry's fields are disclosed. This goes well beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with a front-loaded summary, bullet-style parameter explanations, and a concise return contract. No sentence is wasted and every clause adds operational detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter tool with two optional modes, the description covers all behaviors, return types, and entry fields. Combined with the output schema and read-only annotations, an agent has everything needed to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully defines each parameter: site_url as the Search Console property, sitemap_index as the sitemap-index URL whose children are listed, and feedpath as the exact sitemap URL to fetch. This fully compensates for the schema's lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action and resource: 'List sitemaps on a site' or 'fetch one sitemap by feedpath.' This clearly differentiates it from sibling tools like gsc_list_sites, which lists sites, and query tools, by anchoring on sitemap operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear mode-based guidance: use sitemap_index to list children of an index, use feedpath to fetch a single sitemap, and omit both for the full list. It also notes that this tool absorbs the prior get_sitemap tool. It does not explicitly enumerate sibling alternatives, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every verified Search Console property accessible to this service account.
Returns: {"sites": [{siteUrl, permissionLevel}, ...], "count": N}. permissionLevel: siteOwner | siteFullUser | siteRestrictedUser | siteUnverifiedUser.
Call this first. URL Inspection requires siteFullUser or siteOwner; restricted users cannot inspect.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes safety, and the description adds useful context by showing the return shape, permissionLevel values, and the requirement that URL Inspection needs siteFullUser or siteOwner. It does not cover edge cases like empty results or errors, but for a read-only listing tool the disclosed behavior is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose, return format, permissionLevel enum, and usage ordering are each conveyed in a few short sentences. Every sentence adds information and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool, the description is complete. It explains what is returned, what the permissionLevel values mean, and how this tool relates to the follow-up URL Inspection workflow. The presence of the output schema further reduces the need to document return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to clarify. The baseline of 4 applies because the schema is already complete and the description correctly focuses on the output rather than parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List every verified Search Console property accessible to this service account.' This clearly distinguishes gsc_list_sites from siblings like gsc_list_sitemaps, which list a different resource type. The scope is also explicit: accessible properties for the service account.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit ordering guidance with 'Call this first' and explains why permission levels matter for URL Inspection. It does not explicitly mention when not to use this tool or name an alternative, 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.
Query Search Console traffic data - clicks, impressions, CTR, position.
THE workhorse tool. Supports all six dimensions (incl. HOUR, April 2025), all six search types, full filter compose, pagination, and auto-pagination.
Args:
site_url: "https://example.com/" (URL-prefix) or "sc-domain:example.com" (domain).
start_date / end_date: YYYY-MM-DD (Pacific Time). 16-month retention hard cap.
dimensions: list of {date, query, page, country, device, searchAppearance, HOUR}.
HOUR requires data_state='hourly_all'. searchAppearance cannot be combined with
other dimensions in one query - query it alone and join client-side.
search_type: web (default) | image | video | news | discover | googleNews.
filters: flat list [{dimension, operator, expression}]. Operators:
equals, contains, notEquals, notContains, includingRegex, excludingRegex.
filter_groups: advanced - pass raw dimensionFilterGroups if you need OR logic.
Mutually exclusive with filters.
aggregation_type: auto (default) | byPage | byProperty | byNewsShowcasePanel.
data_state: final (default, ~2-3d lag) | all (fresh, includes unfinalized) |
hourly_all (~10d history with HOUR dimension).
row_limit: per-call cap, 1–25000 (API hard cap).
start_row: 0-based offset for single-page paging.
max_rows: if set (up to 1M), auto-paginate until exhausted or max_rows hit.
Response: {rows, row_count, response_aggregation_type, first_incomplete_date?, first_incomplete_hour?, metadata}. Use first_incomplete_date to distinguish 'data still cooking' from 'data is final' when data_state != 'final'.
Gotchas:
16-month retention. start_date older than 16 months returns empty.
Anonymized queries (fewer than ~a dozen users over 2-3 months) drop from the 'query' dimension but count in totals - page-level data is more complete.
Aggregation shift: with a page filter, totals aggregate byPage (inflates clicks vs property-level). Set aggregation_type explicitly when comparing.
searchAppearance cannot co-exist with other dimensions (API 400).
| Name | Required | Description | Default |
|---|---|---|---|
| filters | No | ||
| end_date | Yes | ||
| max_rows | No | ||
| site_url | Yes | ||
| row_limit | No | ||
| start_row | No | ||
| data_state | No | ||
| dimensions | No | ||
| start_date | Yes | ||
| search_type | No | ||
| filter_groups | No | ||
| aggregation_type | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the readOnlyHint and openWorldHint annotations by disclosing behavioral gotchas: 16-month retention limits, anonymized queries dropping from the query dimension, aggregation shifts under page filters, and searchAppearance incompatibility with other dimensions. It also explains data_state semantics, response fields like first_incomplete_date, and auto-pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long, but it has 12 parameters and no schema-level descriptions, so the length is justified. It is well-structured with Args and Gotchas sections, front-loads the core purpose, and every line adds operational value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the high parameter count and zero schema coverage, the description covers required params, optional behaviors, mutual exclusions, hard limits, response shape, and real-world pitfalls. The presence of an output schema means return-value details do not need repeating, and nothing essential is left missing for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must carry the full burden of parameter semantics, and it does. It documents all parameters with concrete details: date format and timezone, HOUR requiring data_state='hourly_all', search_type values, filter operator list, filter_groups OR logic, aggregation_type options, row_limit cap, start_row offset, and max_rows auto-pagination behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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: 'Query Search Console traffic data - clicks, impressions, CTR, position.' This unambiguously states the tool's function and output metrics. The name and description clearly separate it from sibling tools like gsc_list_sites and gsc_inspect_url.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description positions this as 'THE workhorse tool' and enumerates supported dimensions, search types, filters, and pagination, making it clear this is the default tool for Search Console analytics queries. It does not explicitly name alternatives or state when not to use it, but the sibling tools are sufficiently different that the intended usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1gsc_batch_inspect_urlsgsc_inspect_urlgsc_list_sitemapsgsc_list_sitesgsc_query_search_analyticsScored across 5 tools
Each tool targets a distinct GSC resource: site discovery, search analytics, sitemaps, and URL inspection. The single and batch inspect tools are clearly separated by scope, and descriptions make the boundaries easy to identify.
All tools share the gsc_ prefix and snake_case convention, with clear verbs like list, query, and inspect. The one slight deviation is batch_inspect_urls, which combines an adverb with the verb, but the pattern remains predictable and readable.
Five tools is a well-scoped size for a Google Search Console server focused on reading data and inspecting URLs. Each tool serves a meaningful workflow, and the set is neither bloated nor too thin.
Core GSC workflows are covered: enumerating sites, querying search analytics, reading sitemaps, and inspecting URLs individually or in bulk. Sitemap submission/deletion and site management are absent, but these are minor gaps for a read-oriented analytics server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read-only Search Console analytics, URL inspection, indexing diagnostics, and sitemaps.
Read Search Console performance, keyword opportunities and annotations for your sites.
Search Console SEO analytics: rankings, clicks, CTR, striking-distance insights, charts, sitemaps.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
