Troubleshooting
Start with the symptom. Run gsc doctor for local setup details, then use the matching check below. Problems can come from your client, credentials, Search Console permissions, Google's APIs, or quotas.
My client still runs the old version after updating
The previous MCP server keeps running until you restart the client. Confirm the installed version with gsc --version, compare it with the registry using gsc update --check, then restart your MCP client. Updates never touch tokens, profiles, or client configurations.
My client shows no tools
Run gsc doctor in a terminal. If it passes, regenerate the client entry and follow its instructions:
Print the client configuration
gsc config print --client cursorReplace cursor with your client name, check that the printed runtime and package paths exist, then restart the client. You can also rerun gsc setup --client cursor to refresh its entry.
Google sign-in fails or says AUTH_REQUIRED
Check whether a session exists. For OAuth, start a new sign-in in your terminal and complete the browser flow:
Check and restore OAuth sign-in
gsc auth status
gsc auth loginIf you use a service account, run gsc doctorand confirm the key file still exists at the configured path. Never paste its private key into a chat or website.
A property is missing or returns PROPERTY_NOT_ALLOWED
Compare the requested ID with the allowlist shown by gsc doctor. Search Console IDs must match exactly, including the slash on URL-prefix properties and the sc-domain: prefix on domain properties. Running setup with --site replaces the selected allowlist, so include every property you want to retain:
Configure the allowed properties
gsc setup --client cursor --site 'sc-domain:example.com' --site 'https://shop.example.com/'Repeat --site for each property. Tool calls cannot expand the configured allowlist on their own.
I see a permission or API error
Run the online check to distinguish local setup from Google access:
Check Google access
gsc auth status --onlinePROPERTY_PERMISSION_DENIED: ask a Search Console Owner to grant the signed-in account or service account access to that property.API_DISABLED: enable the Search Console API in the Cloud project that owns the credential.QUOTA_EXCEEDEDorRATE_LIMITED: reduce request volume or concurrency, narrow the query, and retry after the indicated interval. If you use your own OAuth project, check its project and per-user quotas in Google Cloud Console. Quick Connect uses the app's shared project, which you do not administer.
OAuth returns invalid_grant
Google rejected the saved OAuth refresh token. Reconnect the account:
Sign in again
gsc auth loginIf you created your own OAuth app and set its audience to External while it is in Testing, Google expires refresh tokens for these scopes after seven days. Move the app to Production and complete any consent requirements Google presents, or use a service account.
A report is partial or exceeds its request budget
Request fewer rows, shorten the date range, or split a large report into smaller queries. If a response identifies a missing page or slice, retry that part instead of repeating the full request.
An export or page says DATASET_EXPIRED
Run the source query again, then page or export its new result. Temporary datasets expire after 15 minutes.
A write tool is unavailable
Quick Connect is read-only. To use supported write tools, set up your own OAuth client or a service account with full access. For OAuth, rerun setup with --auth custom --access full --reauth and approve the additional Google scopes. A service account needs the required property permission. Changing the configured access mode alone does not add Google scopes or property permissions. Restart the client after setup. See Credentials. The Indexing API accepts URL notifications only for eligible JobPosting or BroadcastEvent pages; it does not guarantee indexing.