Google credentials

Three ways in: Quick Connect signs in with no Cloud setup and stays read-only; your own Desktop OAuth client works for readonly or full access with your own Google Cloud project; a service account is the key-file alternative. Nothing here is pasted into any website — every secret stays in your terminal and your machine.

Not published yet. The pinned runner commands below work only after release @sonnivasquez/gsc-mcp@0.1.0 is confirmed published. Until then there is no public install path, and this page does not establish registry availability.

Quick Connect (readonly)

--auth shared is the built-in sign-in: no Google Cloud project, no console clicks.
It is readonly-only in 0.1.0 — asking for full access with it fails with an explicit error telling you to choose custom or service-account instead.
Embedded OAuth project ownership and public verification remain unestablished. Do not treat Quick Connect as verified for a public release — it is a convenience path, not an audited one.

Desktop OAuth walkthrough

Use your own Google Cloud project when you need full access — or when you want readonly without depending on shared Quick Connect availability and verification, both of which remain unestablished. Your own Desktop client supports either access mode. The click-path below is derived from public Google documentation (sources at the bottom of this page) — no console login was performed to verify it, and Google may rename screens.

Create or select a Google Cloud project. The project is the container for enabled APIs, OAuth clients, and service accounts.
Enable the Search Console API in that project from the API Library. An API key alone does not authorize user data — OAuth is required. Sitemaps are read and submitted through the Search Console API; enable the Indexing API only if you plan eligible URL notifications — pages with JobPosting markup or BroadcastEvent inside a VideoObject.
Fill in Branding (Google Auth Platform → Branding): app name, support email, and homepage. It applies project-wide.
Set the Audience. External means any Google Account can consent (subject to publishing status); Internal is limited to your Workspace organization. While the app is in Testing, at most 100 test users may authorize it — add each account that needs access, including your own, under Audience.
Create a Desktop OAuth client and download the JSON. APIs & Services → Credentials → Create Credentials → OAuth client ID → application type Desktop app → Create → Download JSON. Do not create a Web-application client for this loopback flow. The file holds an installed object with client_id, client_secret, and redirect_uris. It contains a secret: keep it private.
Move the JSON you downloaded into place and lock it down. The download location is wherever your browser saved it — move that file to, for example, ~/.gsc-mcp/client-secrets.json, then set owner-only permissions. Never commit it to a repository, never paste it into any website — including this one.

Secure the directory and secrets file

mkdir -p ~/.gsc-mcp && chmod 0700 ~/.gsc-mcp

Owner-only secrets file

chmod 0600 ~/.gsc-mcp/client-secrets.json

Run setup with the print-first client so nothing is written before you see it — pick the runner that matches your runtime:

Custom OAuth setup — Bun (print-first)

bunx --bun @sonnivasquez/gsc-mcp@0.1.0 setup --client print --auth custom --secrets ~/.gsc-mcp/client-secrets.json --access readonly --site 'sc-domain:example.com'

Custom OAuth setup — Node (print-first)

npx -y @sonnivasquez/gsc-mcp@0.1.0 setup --client print --auth custom --secrets ~/.gsc-mcp/client-secrets.json --access readonly --site 'sc-domain:example.com'

Replace the example property with your exact Search Console ID, and use --access full only if you need write operations.
Sign in when the browser opens. The flow uses a loopback callback at http://127.0.0.1:3847 with a PKCE exchange. Use the Google account that has access to the property. The token is stored only at ~/.gsc-mcp/oauth-token.json, directory 0700, file 0600.
If consent is declined or the account lacks property access, setup fails closed with the reason — fix the account or the allowlist and run it again.

Validator limitation: the 127.0.0.1 requirement

Our validator is stricter than Google. Setup accepts a custom-OAuth JSON only when some installed.redirect_uris entry starts with http://127.0.0.1. Google itself accepts the whole loopback family (127.0.0.1, [::1], localhost), and downloaded Desktop JSON files commonly list http://localhost only — such a file fails our validation even though Google issued it correctly.

Choosing Desktop app → Download JSON therefore does not guarantee passing setup validation. If validation rejects your file, first re-check you downloaded a Desktop app client (not a Web client), then follow the product troubleshooting path.
Never hand-edit Google-issued JSON or secrets to bypass the check — edited credentials are untrustworthy by construction.
The supported alternative today is the service-account path below, which has no redirect-URI requirement.

Service-account alternative

Create the service account in your Cloud project (IAM & Admin → Service Accounts), then Keys → Add key → Create new key → JSON. The download is the only copy of the private key. Move the file you downloaded to, for example, ~/.gsc-mcp/service-account.json with owner-only permissions, never commit it, never paste it into any website.
Grant it on the property. In Search Console go to Settings → Users and permissions → Add user, and add the key’s client_email. Full or Restricted covers standard reads — a service account does not need ownership for read-only analytics. Only an Owner can grant access, and only an Owner can perform owner-level actions.
For Indexing API writes only, delegate ownership. Verify site ownership, then add the service account’s client_email as a delegated owner, with the auth/indexing scope. The Indexing API additionally accepts only pages with JobPosting markup or BroadcastEvent inside a VideoObject — it is not a general indexing tool, notifications only request a crawl, and the default quota is 200 with approval required for more.
Run setup against the key file — pick the runner that matches your runtime:

Owner-only service-account key file

chmod 0600 ~/.gsc-mcp/service-account.json

Service-account setup — Bun (print-first)

bunx --bun @sonnivasquez/gsc-mcp@0.1.0 setup --client print --auth service-account --key-file ~/.gsc-mcp/service-account.json --access readonly --site 'sc-domain:example.com'

Service-account setup — Node (print-first)

npx -y @sonnivasquez/gsc-mcp@0.1.0 setup --client print --auth service-account --key-file ~/.gsc-mcp/service-account.json --access readonly --site 'sc-domain:example.com'

doctor checks that the key file exists — it never reads or prints its contents.

Scopes and access modes

readonly (the default) requests the single scope webmasters.readonly.
full additionally requests webmasters and indexing, and enables Search Console sitemap operations plus eligible URL notifications (Indexing API: JobPosting or BroadcastEvent-in-VideoObject only). It never requests Gmail, Drive, or Analytics scopes.
Change access later without signing in again: setup access readonly|full --client <name>, then restart the client and confirm with doctor.

Testing-mode expiry

Grants to an External app still in Testing expire seven days after consent, including refresh tokens. The only exception is identity-only scopes — Search Console and Indexing scopes do not qualify.
Moving the app to In production lifts the 7-day cap, but tokens stay revocable and expirable for other reasons, and sensitive scopes may need verification. Never promise permanent, free, or publicly verified access.
A token that stops working with invalid_grant is re-authenticated with auth login — see Troubleshooting.

Official Google sources

Verified 2026-10-02 against public documentation only — no console login was performed, and no shared Google project is established. Consult the originals before acting; Google may rename screens after this date.