Google Search Console MCP

Shows whether this server is connected to Google: token presence and source (env variables or a stored in-chat login), expiry, the Google account email, granted vs missing OAuth scopes, where the credentials file lives and where the OAuth client comes from. Makes no network calls and never returns the token itself. Call it first when other tools report the server is not connected.

Takes no parameters.

Step-by-step checklist for connecting this server to Google: creating a Google Cloud project and a Desktop-app OAuth client, publishing the consent screen (mandatory — Testing-mode refresh tokens die after 7 days), downloading the client JSON and handing its PATH to set_client. Works without any credentials; the checklist shortens to 'enable the API + log in' when an OAuth client is already configured (one client serves the whole mcp-google-* line). Never asks the user to paste secrets into the chat.

Takes no parameters.

Saves the OAuth client credentials from the JSON file downloaded from Google Cloud Console ('Download JSON' on a Desktop-app client). Pass the file PATH — the secret must never be pasted into the chat. The client is stored once in the shared ~/.config/mcp-google-auth/client.json (owner-only) and reused by every mcp-google-* server; tokens stay per-server. After this, call start_login.

First step of connecting from the chat, without editing config files or restarting the client. Returns authorizeUrl — show it to the user as a clickable link and ask them to open it in the browser ON THIS MACHINE, pick the Google account and approve access. A one-shot listener on 127.0.0.1 catches Google's redirect; the code is exchanged locally and never passes through the chat. Does not open the browser itself. The attempt lives 10 minutes; when the browser shows the success page, call finish_login.

Takes no parameters.

Second step: waits up to 20 s for the browser consent to finish, saves the tokens to an owner-only file and verifies the login with a read-only identity call, returning the account email and the granted scopes. After success every tool works immediately — no client restart. If the user granted only part of the requested permissions, the login is still saved and missingScopes lists what will not work. Logging in under a different Google account replaces the previous login (its refresh token is revoked best-effort) and the response carries previousAccountEmail so the change never goes unnoticed.

Takes no parameters.

Revokes the stored token at Google (oauth2.googleapis.com/revoke) and deletes the local credentials file. Tokens supplied via env variables are NOT touched — remove them from the MCP client config manually; envTokenStillSet in the response says whether any are still in effect.

Takes no parameters.

Lists every Search Console property the authenticated account can access. Returns { siteEntry: [{ siteUrl, permissionLevel }] } where siteUrl is either a URL-prefix property ("https://example.com/") or a domain property ("sc-domain:example.com"), and permissionLevel is siteOwner, siteFullUser, siteRestrictedUser or siteUnverifiedUser. Call this FIRST: every other tool needs the siteUrl exactly as returned here — a near-match (missing trailing slash, wrong scheme, www vs non-www) is a different property and returns 403/404.

Takes no parameters.

Returns one property's entry: { siteUrl, permissionLevel }. A 404 means the value does not match any registered property — check the exact format (trailing slash, scheme, sc-domain: prefix) against list_sites output.

Adds a property to the account's Search Console set. The property starts UNVERIFIED (permissionLevel siteUnverifiedUser) and most data calls will return 403 until it is verified — verification happens through the Search Console UI or the separate Site Verification API, not through this API. Success is an empty API response (surfaced as { ok: true, added }). Requires the full webmasters OAuth scope (the readonly scope cannot mutate).

Removes (unlinks) a property from the account's Search Console set. No data is deleted and other owners keep their access — this only removes the property from THIS account's list; it can be re-added later. Success is an empty API response (surfaced as { ok: true, removed }). Requires the full webmasters OAuth scope.

Lists the sitemaps submitted for a property (or, with sitemap_index, the children of a sitemap index file). Returns { sitemap: [WmxSitemap] } with per-sitemap path, lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, type (sitemap/rssFeed/atomFeed/patternSitemap/urlList/notSitemap), warnings and errors counts, and contents[] with per-content-type submitted counts. The contents[].indexed field is deprecated and returns nothing useful — never present it as indexed pages.

Returns one submitted sitemap's details (the same WmxSitemap shape as list_sitemaps): errors/warnings counts, isPending, lastSubmitted/lastDownloaded, and per-content-type submitted counts. Useful to check processing status after submit_sitemap.

Submits (or resubmits) a sitemap for the property. The feedpath must be the sitemap's full URL on the property. Success is an EMPTY API response (surfaced as { ok: true, submitted }); processing is asynchronous — check errors/warnings later with get_sitemap. Requires the full webmasters OAuth scope (readonly is not enough).

Removes a sitemap from Search Console. This does not delete the file from the site, and Google may still discover it via robots.txt — it only removes the submission. Success is an empty API response (surfaced as { ok: true, deleted }). Requires the full webmasters OAuth scope.

Runs a Search Analytics (performance) query for a property: clicks, impressions, CTR and average position from Google Search, grouped by the requested dimensions. Each returned row has keys[] (one value per requested dimension, in the same order) plus clicks, impressions, ctr (a FRACTION 0..1, not a percent) and position; rows are sorted by clicks descending. With no dimensions you get one totals row for the range. Dates are calendar dates in Pacific Time and end_date is INCLUSIVE; final data lags ~2-3 days behind (use data_state "all" for fresh, still-changing rows). Pagination: there is no page token — repeat with start_row increased by row_limit until a response comes back with no rows. When grouping by query/page some anonymized long-tail data is never returned, so summed rows will not match a dimensionless totals query. Quota: 1,200 queries/minute per site and per user.

Convenience wrapper over search_analytics for the most common ask: the top search queries for a property, sorted by clicks descending (the API's default order). Each row has keys[0] = the query string plus clicks, impressions, ctr (a FRACTION 0..1) and position. Dates are calendar dates in Pacific Time, end_date inclusive; final data lags ~2-3 days. Anonymized long-tail queries are never returned. Same endpoint and quota as search_analytics — use search_analytics directly for other dimensions, pagination, fresh data or regex filters.

Inspects a URL's status in the Google index (URL Inspection API). Returns { inspectionResult } with: inspectionResultLink (the Search Console UI page for this inspection); indexStatusResult — verdict (PASS/PARTIAL/FAIL/NEUTRAL), human-readable coverageState (e.g. "Submitted and indexed"), robotsTxtState (ALLOWED/DISALLOWED), indexingState, lastCrawlTime, pageFetchState (SUCCESSFUL/SOFT_404/NOT_FOUND/SERVER_ERROR/...), googleCanonical vs userCanonical, sitemap[], referringUrls[], crawledAs (DESKTOP/MOBILE); plus ampResult and richResultsResult (with per-item issues and severities) when applicable. Only the status of the version already in the Google index is returned — this is NOT a live test. mobileUsabilityResult may still appear in responses but the product is retired — ignore it. QUOTA WARNING: only 2,000 inspections per property per DAY (and 600/minute) — throttle any batch inspection and expect 429/403 rateLimitExceeded beyond that.

Escape hatch to call any Google Search Console API path directly, for requests the typed tools don't cover. Two surfaces share the host: "webmasters/v3/..." (sites, sitemaps, searchAnalytics) and "v1/..." (urlInspection). siteUrl and feedpath are PATH SEGMENTS and must be URL-encoded (encodeURIComponent), e.g. "webmasters/v3/sites/sc-domain%3Aexample.com/sitemaps". The path may carry a query string. The Bearer token is added automatically; the method defaults to GET. Note: sites.add and sitemaps.submit are PUT with no body and return an empty response on success.