Search ConsoleFreeFirst-Party Ground TruthRequires Search Console OAuthActive in MCP

Get Search Performance

get_search_performance(domain: string, startDate: string, endDate: string, dimensions?: enum[], rowLimit?: number, startRow?: number, searchType?: enum, dataState?: enum, device?: enum, country?: string, queryContains?: string, pageContains?: string, compareToPreviousPeriod?: boolean)

Query/page/date/country/device performance from Search Console, with filters and period-over-period comparison.

First-party Google Search Console performance data (confidence 1.0) with total clicks, impressions, average CTR, average position, and row breakdowns.

Input Parameters

13 arguments

Parameter	Type	Requirement	Default / Constraints	Description
`domain`	`string`	required	none	A tracked website's primary_domain (e.g. example.com).
`startDate`	`string`	required	ISO date format: YYYY-MM-DD	Start of date range (up to 16 months back from Google Search Console).
`endDate`	`string`	required	ISO date format: YYYY-MM-DD	End of date range.
`dimensions`	`enum[]`	optional	default: `["query"]`1 to 3 items from: query \| page \| date \| hour \| country \| device \| searchAppearance	Break rows down by up to 3 dimensions in order (e.g. ['query', 'device'] cross-tabs queries by device).
`rowLimit`	`number`	optional	default: `25`Integer between 1 and 1000	Max rows to return in the immediate envelope (overflow saved to mcpseo:// export dataset).
`startRow`	`number`	optional	default: `0`Integer min 0	Zero-based row offset for pagination past one rowLimit page.
`searchType`	`enum`	optional	default: `web`web \| image \| video \| news \| googleNews \| discover	Which search surface to report on (web = combined web search; discover = Google Discover feed traffic).
`dataState`	`enum`	optional	default: `final`final \| all	'final': settled data only. 'all': includes provisional data from the last 24–48 hours.
`device`	`enum`	optional	DESKTOP \| MOBILE \| TABLET	Restrict results to one device category.
`country`	`string`	optional	3-character ISO-3166-1 alpha-3 code (e.g. usa, gbr, deu)	Restrict results to one country.
`queryContains`	`string`	optional	none	Convenience filter: restrict to queries containing this substring.
`pageContains`	`string`	optional	none	Convenience filter: restrict to URLs containing this substring.
`compareToPreviousPeriod`	`boolean`	optional	default: `false`	Fetches equal-length preceding period and computes deltas for clicks, impressions, CTR, and position.

Return Envelope (OFE / 1.0)

Open Fact Envelope

Every response adheres to the strict ofe/1.0 envelope schema, returning verified data, typed facts, entity references, and follow-up tool suggestions:

`data` Payload

First-party Google Search Console performance data (confidence 1.0) with total clicks, impressions, average CTR, average position, and row breakdowns.

`coverage` & Freshness

Reports returned count vs total items, observation timestamp as_of, and scope notes. Cached in KV for 1 hour.

`resources` (Dataset Exports)

If a query yields high row counts (e.g. >1,000 queries in Search Console), full unpaginated tables are persisted to R2 and linked as an mcpseo:// URI for follow-up retrieval via export_dataset.

`next_actions`

Provides suggested follow-up tool calls with pre-filled arguments so your AI agent can navigate from discovery to detailed inspection autonomously.

Emitted Facts & Entities

Knowledge Graph

Typed Facts

Facts emitted in the facts[] array with provenance receipts:

Fact Type	Claim Description	Emitted Data Fields
`gsc.performance_summary`	Aggregated period totals for clicks, impressions, CTR, and average position.	`clicksimpressionsctrpositionstart_dateend_date`
`gsc.query_performance`	Per-query or per-dimension performance metrics with optional period-over-period deltas.	`querypageclicksimpressionsctrpositiondelta`

Registered Entities

Entities registered in the entities[] array to establish subject relationships:

property

Tracked Search Console property.

keyword

Reported search queries.

page

Reported landing page URLs.

Request & Response Examples

Live MCP Payloads

Exact JSON schemas transmitted over Model Context Protocol (stdio or HTTP SSE transport):

1. Client Tool Invocationget_search_performance request.json
{
  "tool": "get_search_performance",
  "arguments": {
    "domain": "example.com",
    "startDate": "2026-08-01",
    "endDate": "2026-08-28",
    "dimensions": [
      "query"
    ],
    "compareToPreviousPeriod": true,
    "rowLimit": 25
  }
}

2. Server Envelope Responseget_search_performance response.json
{
  "schema_version": "ofe/1.0",
  "domain": "gsc",
  "data": {
    "domain": "example.com",
    "startDate": "2026-08-01",
    "endDate": "2026-08-28",
    "dimensions": [
      "query"
    ],
    "totals": {
      "clicks": 14250,
      "impressions": 310000,
      "ctr": 0.0459,
      "position": 8.2
    },
    "deltas": {
      "clicks": 1250,
      "impressions": 24000,
      "ctr": 0.0018,
      "position": -0.4
    }
  },
  "facts": [
    {
      "type": "gsc.performance_summary",
      "subject": [
        "urn:property:ws_12345"
      ],
      "data": {
        "clicks": 14250,
        "impressions": 310000,
        "ctr": 0.0459,
        "position": 8.2,
        "start_date": "2026-08-01",
        "end_date": "2026-08-28"
      },
      "provenance": {
        "source_class": "webmaster_console",
        "method": "searchconsole.searchanalytics.query",
        "confidence": 1,
        "observed_at": "2026-09-24T00:00:00Z",
        "cache_hit": true
      }
    },
    {
      "type": "gsc.query_performance",
      "subject": [
        "urn:property:ws_12345",
        "urn:keyword:open+source+seo+mcp"
      ],
      "data": {
        "query": "open source seo mcp",
        "clicks": 3820,
        "impressions": 42000,
        "ctr": 0.0909,
        "position": 1.4,
        "delta": {
          "clicks": 450,
          "position": -0.2
        }
      },
      "provenance": {
        "source_class": "webmaster_console",
        "method": "searchconsole.searchanalytics.query",
        "confidence": 1,
        "observed_at": "2026-09-24T00:00:00Z",
        "cache_hit": true
      }
    }
  ],
  "entities": [
    {
      "id": "urn:property:ws_12345",
      "kind": "property",
      "label": "Example Prod"
    },
    {
      "id": "urn:keyword:open+source+seo+mcp",
      "kind": "keyword",
      "label": "open source seo mcp"
    }
  ],
  "coverage": {
    "returned": 25,
    "total": 420,
    "as_of": "2026-08-28",
    "scope_note": "Top 25 rows shown; full 420 rows available via resources URI."
  },
  "deltas": [],
  "resources": [
    {
      "uri": "mcpseo://gsc/performance/example.com",
      "description": "Full 420 query rows export"
    }
  ],
  "next_actions": [
    {
      "tool": "export_dataset",
      "args": {
        "uri": "mcpseo://gsc/performance/example.com"
      },
      "use_when": "full unpaginated table is needed"
    },
    {
      "tool": "inspect_indexing",
      "args": {
        "domain": "example.com",
        "url": "https://example.com/blog/mcp"
      },
      "use_when": "inspect index health for declining URLs"
    }
  ]
}

LLM Agent Workflow

Claude & Cursor Integration

Step 1

Prompt Trigger

"Why did organic search clicks drop for example.com over the last 28 days?"

Step 2

Agent Decision & Reasoning

The agent calls get_search_performance with compareToPreviousPeriod: true to identify exact queries and pages with negative click and CTR deltas with 1.0 ground-truth confidence.

Step 3

Recommended Follow-up Tools

export_dataset →inspect_indexing →

Provenance Guarantees & Error Handling

Reliability

Source Classwebmaster_console

Inspection Methodsearchconsole.searchanalytics.query

OFE Calibration Score1.00 (OFE 1.0 scale)

Cache Duration1 hour

Every fact emitted by Vouched includes source_class, method, observed_at ISO timestamp, and a published confidence score. LLM agents can inspect these citations to distinguish first-party verified facts (e.g. Search Console) from modeled competitor estimates.

Billing & API Keys

Free on every plan: it reads your own Google data, so there's no per-call cost. Works the same when self-hosted.

Connection Required: Requires connecting your Google Search Console property via OAuth. Until it's connected, calls return a connection_required error saying where to connect it (Settings in the dashboard).

Error Conditions

ConnectionRequiredError: no Search Console site configured for domain. Add connection via /dashboard/connections.

More Search Console Tools

2 sibling tools

Inspect IndexingFree

inspect_indexing()

Google's own indexing status for one URL: indexed?, canonical Google chose, rich results, last crawl.

List SitemapsFree

list_sitemaps()

Submitted sitemaps for a tracked website: last-read status, warnings/errors, submitted counts (Google's indexed count here is deprecated, always 0).

Self-host on GitHub (MIT)Try on Cloud plan