Google Search Console MCP, API and CLI access

Read Search Console reports through MCP, an API or a CLI. Match the property, limit credentials and check query and page data before using an AI client.

A Google Search Console MCP server lets an AI client read authorised search reports through the Model Context Protocol (MCP). Use a third-party server for conversational reporting, Google’s API for controlled scripts or a command-line client for terminal exports. Each route still needs the correct property and Google account permissions.

Choose a maintained reporting method

Google publishes the Search Console API. An MCP server or command-line interface (CLI) adds another way to call it. The examples here have separate publishers, so Google’s API documentation does not establish their behaviour.

Amin Foroutan publishes mcp-gsc, distributed as mcp-search-console. Its repository includes fixes for OAuth scope handling and filtered analytics pagination. It documents local connections from Claude Desktop and other MCP clients.

The jpreagan/gsc-cli project publishes the gsc command. Its repository includes automated tests and a tagged v0.1.0 release. Both projects have public source and are unarchived. Review the code or release you install instead of assuming that similarly named packages have the same publisher.

Compare one reporting job

MethodHow you ask for Australian product queriesWhat you control
MCPAsk the AI client to call the server’s filtered analytics toolAllowed tools, account access and the actual arguments the client sends
Direct APISend a Search Analytics query with explicit filtersRequest construction, pagination and stored output
CLIRun gsc analytics with property and filter flagsShell inputs, output format and any export destination

All three can answer the same reporting question. MCP adds an AI client that can interpret the response. A direct script or CLI can produce a repeatable export without putting private reports into an AI conversation. None of these methods turns property exposure into market-wide keyword volume.

Authorise only the required property access

Read-only reporting needs both an authorised Google identity and a token with the Search Console read scope. Google documents https://www.googleapis.com/auth/webmasters.readonly for reads and https://www.googleapis.com/auth/webmasters for read/write access. Use the read-only scope for this workflow.

OAuth consent applies to the service scope, not one selected property. The account’s Search Console permissions determine which properties it can access. To limit exposure, use an authorised Google account with access only to the required property. An instruction in a prompt is not an access control.

  1. In Google Cloud, enable the Search Console API for the project that owns your OAuth credentials.
  2. Configure the consent screen and create a Desktop app OAuth client. If the application is in testing, add the intended account as a test user.
  3. Download the client JSON into a private local credential location. Keep it out of shared projects and report exports.
  4. Complete the selected client’s OAuth flow with the account that already has Search Console property access.
  5. Inspect the granted scope, list accessible properties and copy the exact property identifier before requesting data.

The Domain-property identifier is sc-domain:example.com. A URL-prefix identifier can be https://example.com/. Preserve its protocol, hostname and trailing slash. Google’s Sites list method returns property identifiers and permission levels.

Connect Claude Desktop to the local MCP server

For mcp-gsc, install the prerequisite uv tool using the repository’s installation instructions. Configure Claude Desktop to launch uvx with mcp-search-console over standard input/output. The client launches the local server, which calls Google’s API.

Set GSC_OAUTH_CLIENT_SECRETS_FILE to the absolute path of your private client JSON. Leave GSC_ALLOW_DESTRUCTIVE false and set GSC_DATA_STATE to final for completed reporting periods. The project documents this Claude Desktop setup.

Restart Claude Desktop after saving its MCP configuration. Complete the Google sign-in flow when the server requests it. Ask the client to call get_capabilities, then list_properties. Match the returned property to your intended store before allowing a report call.

A connected server proves that Claude can reach a process. It does not prove that the process has the right Google account or property. The server’s authentication and analytics implementation defines the tool arguments and scope selection.

Keep downloaded credentials, OAuth tokens and authentication responses out of prompts and logs. Pass a local credential-file path through configuration rather than pasting the file contents. Share only the report rows the analysis requires.

Use the CLI without an AI client

Install gsc-cli from its published release or documented Homebrew tap. Import your downloaded client JSON with gsc auth credentials, supplying its private local path. Then run:

gsc auth add --readonly
gsc sites

The CLI setup instructions document credential storage under ~/.gsc/credentials/. The --readonly option matters because the ordinary authorisation command does not request read-only access by default.

Request and verify a retail query/page report

Request a narrow report first, then compare it with Search Console using equivalent settings. Use this fictional lighting-store job: Australian Web searches for outdoor questions reaching product pages, over 28 days ending three days ago.

Use Google’s Pacific Time reporting boundary. Count both the start and end day. The following Python snippet builds the API request body without exposing credentials or embedding arbitrary calendar dates:

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

report_end = datetime.now(ZoneInfo("America/Los_Angeles")).date() - timedelta(days=3)
report_start = report_end - timedelta(days=27)
site_url = "sc-domain:example.com"
request_body = {
    "startDate": report_start.isoformat(),
    "endDate": report_end.isoformat(),
    "type": "web",
    "dimensions": ["query", "page"],
    "dimensionFilterGroups": [{
        "groupType": "and",
        "filters": [
            {"dimension": "country", "operator": "equals", "expression": "aus"},
            {"dimension": "page", "operator": "contains", "expression": "/products/"},
            {"dimension": "query", "operator": "contains", "expression": "outdoor"}
        ]
    }],
    "aggregationType": "auto",
    "dataState": "final",
    "rowLimit": 100,
    "startRow": 0
}

Pass site_url and request_body to an authorised client’s searchanalytics.query operation. The snippet constructs inputs only. Google’s query reference defines the request and response.

For mcp-gsc, ask Claude to call get_advanced_search_analytics with the same period and property. Use dimensions="query,page", search_type="WEB", data_state="final" and row_limit=100. Its filters argument takes a JSON-encoded array containing the three filter objects, rather than the entire API request body.

The CLI accepts equivalent filters in its analytics command: --filter country=equals=aus, --filter page=contains=/products/ and --filter query=contains=outdoor. Use --dimensions query,page, --type web and --row-limit 100. Supply explicit --start-date and --end-date values matching the calculated period. Omitted dates use the CLI’s own default period, so they would change this comparison.

Interpret the fictional response

Suppose the direct API returns this row:

{
  "keys": ["cedar wall light outdoor", "https://example.com/products/cedar-wall-light/"],
  "clicks": 6,
  "impressions": 240,
  "ctr": 0.025,
  "position": 8.4
}

The first key is the query and the second is the page because the request orders dimensions that way. Six clicks from 240 impressions produce a CTR of 2.5%. Position 8.4 is an average across the returned grouping’s impressions. Customers can see different positions for individual searches.

mcp-gsc returns named dimension fields instead of the API’s keys array. It also includes applied filters and pagination information. Its metric sorting happens within the returned page of rows, so sorting 100 rows cannot identify the highest-impression query across an entire store.

Google’s performance-data guide explains the limits. A request can return up to 25,000 rows, with pagination through startRow. The API exposes at most 50,000 rows per day per search type. Query/page detail can lose data, so exhausting returned rows still does not prove every underlying search is present.

Cross-check before changing product guidance

  1. Open the same property’s native Search results report. Select Web and the same inclusive date range.
  2. Filter country to Australia, pages to URLs containing /products/ and queries to those containing outdoor.
  3. Select the exact query, then inspect Pages for the product URL. Compare the corresponding row, rather than a site-wide chart total.
  4. Check the response’s property and applied filters. Investigate missing or different figures before treating the extract as complete.

Google’s data-discrepancy guidance explains aggregation differences and omitted anonymised queries. Keep recent preliminary data out of a final-data comparison. Canonical attribution can also move exposure to another URL.

For the fictional wall light, read the actual product page and manufacturer’s supplied restrictions. If the page omits whether sheltered outdoor use is allowed, correct the published answer from that evidence. The report identifies a question to investigate. It does not establish the product’s suitability or prove a future ranking improvement.

Handle missing access and revoke the connection

Diagnose a report failure by checking the Google identity and exact property first. A working MCP connection can still return an empty property list or an authorisation error.

SymptomCheckCorrection
Empty list or wrong storeCompare list_properties or gsc sites with the signed-in accountAuthorise the correct account or have an owner grant the required property access
Property not foundCompare the exact Domain or URL-prefix identifierCopy the listed identifier. Inspect hostname and protocol differences
Expired or revoked consentRead the authentication error without exposing its tokenUse mcp-gsc’s reauthenticate tool or repeat gsc auth add --readonly
API disabled or access forbiddenCheck the Google Cloud project, API enablement and scopeEnable the API in the credential-owning project or correct the account’s permission
Unknown tool or unsupported argumentInspect get_capabilities and the installed version’s tool definitionUse the operation that implementation supports. Do not invent tool names
Empty reportCheck filters and data availabilityTest a smaller known query in the native interface before widening the extraction

The MCP repository documents its authentication diagnostics. Google’s API error reference distinguishes invalid requests from authorisation failures. A URL inspection operation reads indexed information. It is not the native interface’s Request indexing action.

To disconnect, stop the client’s MCP server connection and remove its configuration entry. Use Google Account’s linked-app access controls to remove the application’s access. Remove stored client credentials and token files from the private locations that implementation uses. Disconnecting a client alone does not revoke its OAuth grant.

If you granted a separate Google identity access only for this integration, a property owner can remove that identity from Search Console. Keep an authorised owner in place. Check that the old connection can no longer retrieve the report.

Report-reading permission does not grant authority to publish product pages or edit your store’s source content. Give any publishing system separate permissions and approval rules. Review the suggested correction against the product evidence before it reaches customers.

Give your store its own shopping agent

Customers ask in their own words. Your agent finds, compares and checks out from your catalogue, right on your site.

See it in actionFree trial · Simple setup