Google credentials
Start with Quick Connect. It needs no Google Cloud project and grants read-only access. Use your own OAuth client or a service account if you need Google write operations.
Answer setup step 1
Setup asks two questions up front. Press Enter to accept each default, or type the number of the option you want.
- Authentication:
Quick Connect (recommended, read-only, no indexing),Custom OAuth (full access, indexing), orService Account (full access, indexing). Quick Connect is read-only; full access needs your own OAuth client or a service account. - Access level (skipped for Quick Connect):
Read only (data only)orFull (data + indexing). Full access asks a separate confirmation before enabling Google write operations.
Quick Connect
Quick Connect uses the shared OAuth app and the webmasters.readonly scope. It cannot submit sitemaps or send URL indexing notifications. Setup opens Google sign-in, lets you choose properties, and saves the OAuth token on your machine under ~/.gsc-mcp/.
Connect a client with read-only Quick Connect
gsc setup --client desktop --auth shared --access readonlyReplace desktop with code, cursor, codex, opencode, or pi for another supported client. Google sign-in happens in your browser. Your MCP client and AI provider receive the tool results, subject to their own data policies. See the privacy page for details.
Read-only and full access
Read only (data only)is the default. It requests onlywebmasters.readonlyand enables Search Console reads.Full (data + indexing)adds the Search Console write scopewebmastersand Indexing API scopeindexing. It can submit sitemaps and send URL notifications. Indexing API notifications are limited to eligible pages with JobPosting or BroadcastEvent markup. Setup still asks a separate yes-or-no question before enabling writes.- Quick Connect is read-only. Choose custom OAuth or a service account for full access. The authenticated Google account or service account still needs permission for each property.
--yesaccepts the defaults, so it never turns on write operations, the sample query, or the agent skill install.
Use your own OAuth client
This option uses your Google Cloud project and works with read-only or full access.
- Create or select a Google Cloud project and enable the Search Console API.
- In Google Auth Platform, set the app name, support email, audience, and requested scopes. External apps in Testing can use up to 100 listed test accounts; refresh tokens for these non-basic scopes expire after seven days. Follow Google's consent and verification steps for the scopes and audience you choose.
- Create an OAuth client with application type Desktop appand download its JSON file. Setup currently requires a redirect URI that starts with
http://127.0.0.1. It rejects files that list onlylocalhostor[::1]; do not edit Google's JSON to bypass that check. - Keep the JSON on your machine. For example, store it at
~/.gsc-mcp/client-secrets.jsonand restrict access to your account:Create a private credentials directory
mkdir -p ~/.gsc-mcp && chmod 0700 ~/.gsc-mcp chmod 0600 ~/.gsc-mcp/client-secrets.json - Run setup with your client JSON and exact Search Console property ID:Replace the example property with your own ID. Add
Set up Desktop OAuth
gsc setup --client desktop --auth custom --secrets ~/.gsc-mcp/client-secrets.json --access readonly --site 'sc-domain:example.com'--siteagain for each additional property. Use--access fullonly when you need write operations.
Use a service account
- In a Google Cloud project, enable the Search Console API, create a service account, and download a JSON key. Store the key at
~/.gsc-mcp/service-account.jsonand restrict it to your account:Protect the service-account key file
mkdir -p ~/.gsc-mcp && chmod 0700 ~/.gsc-mcp chmod 0600 ~/.gsc-mcp/service-account.json - In Search Console, add the service account's
client_emailto each property. An Owner must grant property access. Use a permission level that allows the operations you need. - Run setup with the key path and property ID:Use
Set up a service account
gsc setup --client desktop --auth service-account --key-file ~/.gsc-mcp/service-account.json --access readonly --site 'sc-domain:example.com'--access fullfor supported write operations. Indexing API requests also require the service account to be an eligible owner and the page to use JobPosting or BroadcastEvent markup.
Google setup references
- OAuth for desktop apps
- Create a Desktop OAuth client
- OAuth audience and testing status
- Create and protect service-account keys
- Search Console users and permissions
- Search Console API scopes and quotas
- Indexing API prerequisites