Google Search Console connector: search performance, index status and sitemaps

This page is for SEO leads and the IT admin who owns the company's Google Cloud project. It explains the OAuth client you create, which Search Console permission each tool needs, how property names are written, and why recent days and long tails are missing from the results.

The connector reads the Search Analytics and URL Inspection parts of the Search Console API and can submit sitemaps. It signs in as a Google user through OAuth 2.0 with PKCE, using a client that you create in your own Google Cloud project. OrgRelay never borrows a shared vendor client. The connector spec covers the general model.

#What staff can ask

• "Which queries brought the most clicks to the blog last month?" This calls seo.keywords on the property with last month's dates. Add a keyword filter to narrow it, for example to queries containing "pricing".
• "Which /docs/ pages lost impressions in September compared with August?" This calls seo.pages twice with url_contains: /docs/, once per month. OrgRelay compares the two results.
• "How does mobile compare with desktop this quarter?" This calls seo.breakdown with dimension: device.
• "Is the new pricing page indexed yet, and which canonical did Google pick?" This calls seo.inspect_url.
• "Resubmit the sitemap after today's release." This calls seo.submit_sitemap, which waits for approval.

All tools sit in the seo.* domain from standard tools. A content team can therefore ask the same kind of question of other search tools later without learning new names. To connect landing-page traffic to leads, pair it with the HubSpot connector.

#Tools

How the results are shaped:

• Property names must match Search Console exactly. A URL-prefix property is written with its trailing slash, https://www.example.com/. A domain property is sc-domain:example.com. Run seo.sites first if you are unsure.
• Rows page through startRow. limit defaults to 50 and can go up to 25,000, the API's own maximum per request. When a page comes back full, the result includes a next_cursor, which the connector sends as startRow on the next call. Google still describes the API as returning top rows rather than every row, so very long tails can be incomplete.
• Numbers are rounded. CTR is returned as a percentage with two decimals, and position with one decimal.
• Countries use three letters. Codes are ISO alpha-3, such as usa, deu or idn. A two-letter code matches nothing.
• Unknown dimensions fall back. If seo.breakdown gets a dimension other than country, device or date, it uses country.
• Dates are Pacific Time. The Search Analytics API reads date_from and date_to in PT, not in your office's time zone.

#Credentials, scope and permissions

The connector has two fields of its own, the OAuth client ID and the OAuth client secret. When you click Authorize in OrgRelay, Google asks the signing-in user to consent. The resulting refresh token is stored encrypted, and access tokens are renewed automatically. OrgRelay asks for offline access and forces the consent prompt, so Google always returns a refresh token.

By default the connector requests https://www.googleapis.com/auth/webmasters, the read-and-write scope that sitemap submission needs. An advanced field, Read-only authorization, changes that: set it to yes and the consent screen asks only for webmasters.readonly. A read-only connection refuses seo.submit_sitemap with a message telling you to switch the field back to no and authorize again. The read-only option requires OrgRelay 1.4.0 or later.

The Google account also needs a permission level on each property:

• Any level, including Restricted user: enough to read performance data through seo.keywords, seo.pages and seo.breakdown, and to use seo.inspect_url. Google describes URL Inspection for restricted users as fetch-only.
• Full user or Owner: needed for seo.submit_sitemap. Google allows only owners and full users to submit sitemaps.

The OAuth consent setup decides how long the authorization lasts. With the audience set to Internal, available on a Google Workspace domain, only company accounts can sign in and no Google review is needed. With External, the app must be published. In the publishing status Testing, Google expires a test user's authorization seven days after consent, refresh token included, so the connection would break every week. Click Publish app under Audience to move it to In production. For an app only your own staff use, the consent screen may warn that Google has not verified the app; choose Advanced and continue. The auth page explains how OrgRelay handles OAuth connectors in general, and the security model covers where tokens live.

#Which actions need approval

Only seo.submit_sitemap writes. It creates an approval request showing the property and the sitemap URL, and it runs only after the owner or a designated approver accepts it. The approver should check two things. First, the sitemap URL must belong to the property. Second, the sitemap should be one you mean Google to read now. On approval the connector sends PUT /webmasters/v3/sites/{site}/sitemaps/{feedpath} with no body. Google does not return a processing result in that response; check the Sitemaps report later for the outcome.

The approved call carries the idempotency key orgrelay-approval-<approval id>. Google's endpoint has no idempotency header, so the key stays inside OrgRelay. More on the flow is in approvals and writes and human in the loop.

#Set it up

1. In the Google Cloud console, choose or create a company project and enable the Google Search Console API.
2. Open Google Auth Platform. Under Branding, name the app OrgRelay. Under Audience, pick Internal if you use Google Workspace. Otherwise pick External and click Publish app, so the status reads In production rather than Testing.
3. Under Clients, create a client of type Web application. Add the redirect URI that OrgRelay shows on the connection form, which is your OrgRelay address followed by /oauth/callback. Copy the client secret straight away; Google shows it only when the client is created.
4. In OrgRelay, open Admin → Business systems → App directory, pick Google Search Console, and enter the client ID and secret. If staff should only read data, set Read-only authorization to yes under the advanced settings. Click Authorize. Sign in with the Google account that has access to your properties. OrgRelay lists the properties it can see.
5. Grant the connector to the marketing or content role. Keep seo.submit_sitemap for the people who own releases.

If you are adding a different search tool of your own, served over the MCP transport, the quickstart and connector check show how to build and test it.

#Limits and data caveats

Google's usage limits allow 1,200 Search Analytics queries per minute per site and 1,200 per user. URL Inspection allows 2,000 inspections per day and 600 per minute per site. The daily inspection cap is the one you can reach, for example when someone asks the assistant to check hundreds of URLs one by one. OrgRelay limits each connection to 120 calls per minute by default and pauses for 60 seconds after three failures in a row. If Google returns 429, OrgRelay waits for Retry-After, or 60 seconds.

What the data can and cannot show:

• Recent days are missing. Google says collected data is normally available within 2 to 3 days. The connector requests final data only, so the latest days are left out rather than shown partially.
• History is limited. Search Console keeps about 16 months of performance data. Older dates return nothing.
• Low-volume rows are left out. Some queries are anonymized and omitted, so per-query totals add up to less than per-page or per-country totals.
• There is no test property. Use your own verified property. The read tools change nothing.

The connector does not add or verify properties, manage users, remove URLs, request indexing, or read the Core Web Vitals and Page Experience reports. Results longer than about 12,000 characters are cut before the AI sees them. Large pages of rows are useful for exports and for OrgRelay's own processing, but for a question in chat a few hundred rows is usually enough.

#Official MCP server and OrgRelay

Google has not published an official MCP server for Search Console. Several open-source Search Console MCP servers exist, built by third parties on the same API. A server that is reachable over HTTP and accepts a token in a request header can be added to OrgRelay as a third-party MCP connection. Servers that run locally over stdio, or that need an interactive OAuth sign-in with PKCE, cannot be connected directly, and many of the community Search Console servers run over stdio. Our list of official MCP servers tracks which vendors ship their own.

Whichever server you use, OrgRelay adds the controls a team needs: grants per role, an approval before any write, one audit log across Search Console, your CMS and your other systems, and all of it running on the company's own machine. The business-level list of supported systems is on OrgRelay integrations. The enterprise patterns page explains the trade-offs. If your developers prefer to query Search Console from an editor, see Claude Code and Codex. An agent skill can also package a repeatable monthly SEO report on top of these tools.

#Common questions

Why are the last two or three days missing from the numbers?

The connector asks the Search Analytics API for final data only, which is the API default. Google says collected data is normally available in 2 to 3 days, so the most recent days are absent rather than partial. Ask for ranges that end a few days ago.

Can we use a service account instead of a person's Google account?

Not with this connector. It only offers the OAuth sign-in flow, so it acts as the Google user who authorized it and sees the properties that user can see. Use a shared company account with the right Search Console permissions if you do not want it tied to one employee.

The connection stopped working after a week. Why?

If the OAuth app's audience is External and its publishing status is Testing, Google expires the authorization seven days after consent, refresh token included. Set the audience to Internal on a Workspace domain, or click Publish app so the status becomes In production, then authorize again.

#Related

• All connectors
• HubSpot connector to tie search traffic to leads
• Security model
• MCP transport
• Human in the loop