API reference: Google Search Console

All tools are read-only and are called via tools/call over POST /gsc/mcp. You need an active Google Search Console subscription, your user must hold a seat on it (assigned under Team in the portal, see Team), and your authorized Google account must have access to the properties you query. In tools/list every tool has a title and the annotations readOnlyHint: true, destructiveHint: false and openWorldHint: false. A successful result contains the payload twice: as JSON text in content and as the same object in structuredContent. The examples below show that payload. If your account has no Google Search Console subscription, or your user has no seat on it, the initialize result includes instructions explaining how to get access.

Endpoint: https://mcp.consile.ai/gsc/mcp. GSC is its own named connector: tools/list returns the seven tools below plus the connect_account system tool. An account without a Google Search Console subscription sees only connect_account. Section headings use the bare tool name. In requests, always send the namespaced name (for example gsc__top_queries). A bare name returns Unknown tool.. The connector is multi-instance: each additional Google account (a “portal” in the portal UI) has its own endpoint and tool prefix, e.g. https://mcp.consile.ai/gsc-2/mcp with tools named gsc-2__<tool>. Portals are added in the portal by an administrator.

Access to Google is renewed automatically. If the Google access has expired or was revoked, the tool result has isError: true and asks for a reconnect: Search Console access token has expired; reconnect required or Search Console rejected the access token (401); reconnect required. To reconnect, call connect_account to get a fresh connect link, or open the connector in the portal, click Disconnect connector (Afbryd connector in the Danish UI) and connect it again. That button is for the first portal; for an extra portal, call connect_account on that portal’s endpoint (for example /gsc-2/mcp). The portal can show the connector as connected until you reconnect.If Google rejects a call for another reason (for example the Google account has no access to the property), or the call times out, the result text is Tool invocation failed. without the cause. First check with gsc__list_sites that the property is listed, and pass its siteUrl exactly as listed. See Errors and Errors & limits.

Common parameters

string

required

A Search Console property. Either a URL-prefix property (https://www.example.com/) or a domain property (sc-domain:example.com). Get valid values with list_sites.

string (YYYY-MM-DD)

required

Date range for the report, in the format YYYY-MM-DD. The fixed tools (top_queries, top_pages, query_performance, page_performance and compare_periods) send no type or dataState, so Google’s defaults apply: web search only, and finalized data only. The most recent days (typically two to three) are therefore missing. Use search_analytics_query with dataState: "all" to include fresh, preliminary data.

list_sites

Lists the Search Console properties of the authorized Google account, with your permission level. Properties with permissionLevel siteUnverifiedUser return no data. Arguments: none.

array

List of properties.

Show fields

string

The property identifier.

string

Your access to the property as reported by Google (e.g. siteOwner, siteFullUser, siteRestrictedUser, siteUnverifiedUser).

{ "name": "gsc__list_sites", "arguments": {} }

{
  "sites": [
    { "siteUrl": "sc-domain:example.com", "permissionLevel": "siteOwner" },
    { "siteUrl": "https://shop.example.com/", "permissionLevel": "siteFullUser" }
  ]
}

top_queries

The most-clicked search queries for a property over a date range.

string

required

string (YYYY-MM-DD)

required

string (YYYY-MM-DD)

required

integer

default:"10"

Max number of rows. Integer between 1 and 25000.

array

Rows sorted by clicks. Each item has query, clicks, impressions, ctr and position.

{
  "name": "gsc__top_queries",
  "arguments": {
    "siteUrl": "sc-domain:example.com",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28",
    "limit": 5
  }
}

{
  "siteUrl": "sc-domain:example.com",
  "startDate": "2026-05-01",
  "endDate": "2026-05-28",
  "queries": [
    { "query": "example keyword", "clicks": 421, "impressions": 9120, "ctr": 0.046, "position": 7.8 }
  ]
}

top_pages

The most-clicked pages for a property over a date range. Same arguments as top_queries (limit defaults to 10, max 25000).

array

Rows sorted by clicks. Each item has page, clicks, impressions, ctr and position.

{
  "name": "gsc__top_pages",
  "arguments": {
    "siteUrl": "sc-domain:example.com",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28"
  }
}

{
  "siteUrl": "sc-domain:example.com",
  "startDate": "2026-05-01",
  "endDate": "2026-05-28",
  "pages": [
    { "page": "https://example.com/", "clicks": 980, "impressions": 21340, "ctr": 0.046, "position": 5.1 }
  ]
}

query_performance

Clicks, impressions, CTR and position for a single query.

string

required

string

required

The exact search query to report on.

string (YYYY-MM-DD)

required

string (YYYY-MM-DD)

required

object

clicks, impressions, ctr, position. If the query has no data in the period, zeros are returned.

{
  "name": "gsc__query_performance",
  "arguments": {
    "siteUrl": "sc-domain:example.com",
    "query": "example keyword",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28"
  }
}

{
  "siteUrl": "sc-domain:example.com",
  "query": "example keyword",
  "startDate": "2026-05-01",
  "endDate": "2026-05-28",
  "metrics": { "clicks": 421, "impressions": 9120, "ctr": 0.046, "position": 7.8 }
}

page_performance

Like query_performance, but for a single page. Use page (exact page URL) instead of query. Returns zeros if the page has no data in the period.

string

required

string

required

The exact page URL to report on.

string (YYYY-MM-DD)

required

string (YYYY-MM-DD)

required

{
  "name": "gsc__page_performance",
  "arguments": {
    "siteUrl": "sc-domain:example.com",
    "page": "https://example.com/product",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28"
  }
}

{
  "siteUrl": "sc-domain:example.com",
  "page": "https://example.com/product",
  "startDate": "2026-05-01",
  "endDate": "2026-05-28",
  "metrics": { "clicks": 132, "impressions": 4010, "ctr": 0.033, "position": 9.4 }
}

compare_periods

Compares Search Analytics totals between two periods, with absolute and percentage differences. The response contains totals and deltas only, not a per-row breakdown. With dimension set, each period’s totals are computed from up to 25,000 rows of that dimension (clicks and impressions summed, ctr = clicks / impressions, position impression-weighted). These totals can be lower than the site-wide numbers when Google leaves rows out, for example anonymized queries. Omit dimension to get Google’s site-wide totals. To compare individual queries or pages, call gsc__search_analytics_query once per period.

string

required

string (YYYY-MM-DD)

required

string (YYYY-MM-DD)

required

string (YYYY-MM-DD)

required

string (YYYY-MM-DD)

required

string (enum)

Optional: query, page, country, device, searchAppearance or date. Changes how the totals are computed; it does not add a breakdown to the response. Omit for site-wide totals.

object

{ startDate, endDate, totals }, where totals is clicks, impressions, ctr, position.

object

Differences, computed as period B minus period A, so period A is the baseline. Pass the earlier period as A. clicks and impressions have { absolute, percent }, where percent is relative to period A and is null if period A’s value was 0. ctr and position have { absolute }. For position a lower value is better, so a negative delta means the average ranking improved.

{
  "name": "gsc__compare_periods",
  "arguments": {
    "siteUrl": "sc-domain:example.com",
    "periodAStart": "2026-04-01",
    "periodAEnd": "2026-04-28",
    "periodBStart": "2026-05-01",
    "periodBEnd": "2026-05-28"
  }
}

{
  "siteUrl": "sc-domain:example.com",
  "dimension": null,
  "periodA": { "startDate": "2026-04-01", "endDate": "2026-04-28", "totals": { "clicks": 3800, "impressions": 81000, "ctr": 0.047, "position": 8.1 } },
  "periodB": { "startDate": "2026-05-01", "endDate": "2026-05-28", "totals": { "clicks": 4200, "impressions": 86000, "ctr": 0.049, "position": 7.6 } },
  "delta": {
    "clicks": { "absolute": 400, "percent": 10.5 },
    "impressions": { "absolute": 5000, "percent": 6.2 },
    "ctr": { "absolute": 0.002 },
    "position": { "absolute": -0.5 }
  }
}

search_analytics_query

Advanced: send a raw Search Analytics query straight through to the Search Console API. For power users who want the full surface (dimensions, filters, pagination, search type and fresh data).

string

required

object

required

Raw Search Analytics request body. Fields not listed here are ignored (for example the legacy searchType; use type).

Show fields

string (YYYY-MM-DD)

required

string (YYYY-MM-DD)

required

string[]

Any of query, page, country, device, searchAppearance, date.

array

{ groupType?: "and", filters: [{ dimension, operator?, expression }] }. operator is equals, notEquals, contains, notContains, includingRegex or excludingRegex.

string (enum)

web, image, video, news, discover, googleNews. Google’s default is web.

string (enum)

auto, byPage, byProperty.

string (enum)

all (includes fresh, preliminary data) or final (Google’s default).

integer

1 to 25000.

integer

Zero-based offset for pagination (≥ 0).

string | null

How Google aggregated the rows, or null.

array

Raw rows: keys (one value per requested dimension, in order), clicks, impressions, ctr, position.

{
  "name": "gsc__search_analytics_query",
  "arguments": {
    "siteUrl": "sc-domain:example.com",
    "requestBody": {
      "startDate": "2026-05-01",
      "endDate": "2026-05-28",
      "dimensions": ["query", "device"],
      "dimensionFilterGroups": [
        { "filters": [{ "dimension": "country", "operator": "equals", "expression": "dnk" }] }
      ],
      "rowLimit": 100,
      "dataState": "final"
    }
  }
}

{
  "siteUrl": "sc-domain:example.com",
  "responseAggregationType": "byProperty",
  "rows": [
    { "keys": ["example keyword", "MOBILE"], "clicks": 210, "impressions": 5400, "ctr": 0.039, "position": 8.2 }
  ]
}

connect_account

connect_account is a system tool that the GSC endpoint lists next to the seven GSC tools (title “Connect your account”). It takes no arguments and is read-only. Its name has no gsc__ prefix. It returns { "connect_url": "…", "instructions": "…" }. The user opens connect_url in a browser and is sent to Google to approve read-only Search Console access. The link expires after 10 minutes. It only works for accounts that subscribe to Google Search Console, and for users who have accepted Consile’s terms in the portal. Use it also to reconnect, for example after access was revoked at Google: completing the flow replaces the existing connection for that endpoint.

Request

{ "name": "connect_account", "arguments": {} }

Errors

Tool failures come back as a normal tools/call result with isError: true and a short text, not as a JSON-RPC error.

Situation	Text in the result
Bare tool name (e.g. `top_queries`) or another connector’s tool	`Unknown tool.`
No Google Search Console subscription	A message with the purchase link `https://app.consile.ai/connectors/gsc`
Subscription exists, but your user has no seat	A message asking a Consile administrator to assign you under Team
Google account not connected yet	`gsc is not connected yet. Connect it here: <link>`
Google access expired or revoked	`Search Console access token has expired; reconnect required` or `Search Console rejected the access token (401); reconnect required`
Invalid arguments (e.g. a date not in `YYYY-MM-DD` format, `limit` above `25000`)	`Tool invocation failed.`
Google rejected the call for another reason (no access to the property, timeout, other Google error)	`Tool invocation failed.`

Requests to the endpoint are also rate-limited per account and connector. When the limit is exceeded you get HTTP 429 (JSON-RPC error -32029, Retry-After: 1) instead of a tool result. Google’s own Search Console API quotas apply on top. See Errors & limits for the current limits.

Fields like ctr (0 to 1) and position follow the Search Console API’s own definitions. See Errors & limits for limits and data freshness.

Introduction

Connect an MCP client

API reference

API reference: Google Search Console

Common parameters

list_sites

top_queries

top_pages

query_performance

page_performance

compare_periods

search_analytics_query

connect_account

Errors

​Common parameters

​list_sites

​top_queries

​top_pages

​query_performance

​page_performance

​compare_periods

​search_analytics_query

​connect_account

​Errors

Common parameters

list_sites

top_queries

top_pages

query_performance

page_performance

compare_periods

search_analytics_query

connect_account

Errors