Command reference
Use gsc for setup and maintenance. Your MCP client starts the server automatically after setup.
Common commands
Set up, check, and sign in
gsc setup
gsc doctor
gsc auth status
gsc auth status --online
gsc --help
gsc --versionConnect Google and a client
Example: connect Cursor with read-only Quick Connect
gsc setup --client cursor --auth shared --access readonlySetup opens Google sign-in, lets you choose Search Console properties, and configures the client. It runs quietly by default: add --verbose for the full detail (JSON entries, paths, and verification) or --dry-run to preview without changes. Replace cursor with desktop, code, codex, opencode, or pi. For other clients, use generic or print to generate a configuration.
--client <target>selects the destination (repeatable or comma-separated). OpenCode and Pi are configured globally only.--auth shared|custom|service-accountchooses Quick Connect, your OAuth client, or a service account.--access readonly|fullselects access. Read-only is the default; Quick Connect supports read-only only.--site <property-id>may be repeated, once per exact property ID. Use--site allalone or--all-sitesto allow all current and future properties. The options are mutually exclusive.--secrets <path>supplies a Desktop OAuth JSON file.--key-file <path>supplies a service-account JSON file.--dry-runpreviews setup without Google sign-in or client changes.--reauthstarts a fresh OAuth sign-in.--verboseprints the full detail.--forceor--yesskips the client configuration confirmation.--yesnever opts in to writes, the sample query, or the skill install.--language en|essets setup language.
Change an existing access mode
Change a client to read-only
gsc setup access readonly --client cursorUse full only when you need Google write operations. This changes the client configuration only. Quick Connect remains read-only. For OAuth, rerun setup with --auth custom --access full --reauth and approve the additional Google scopes. A service account needs the required property permission. Restart the client after setup.
Deprecated write flags
--access readonly|full. The older write commands remain for existing configurations.Legacy write commands
gsc setup enable-write --client cursor
gsc setup disable-write --client cursor--scopes and --enable-write are also legacy setup flags. The write commands warn first (writes make real changes in Google, limited to 200 URL notifications per day), need confirmation, and refuse Quick Connect installs.
MCP server
Start the server manually
gsc serve
gsc serve --profile reportingMCP clients normally start the server for you. A profile uses its own property allowlist and datasets. In-memory datasets expire after 15 minutes.
MCP tools
Explore the complete MCP tool catalog and access requirements.
On-demand audits
See the audit guide for inputs, limits, continuation, and evidence. The history guide covers optional local records and snapshots.
Analytics dimensions
See analytics and timelines for brand classification, country and device lists, web multimodal reports, hourly data, and search appearances.
Diagnose the installation
Run local or online checks
gsc doctor
gsc doctor --onlineThe local check reports runtime, paths, configuration, and authentication state without printing secrets. The online check also validates access to Search Console and includes a version check against the npm registry that never fails on version drift.
Compare installed and registry versions without installing
gsc update --checkManage Google sign-in
Sign in, check status, or remove a session
gsc auth login
gsc auth status
gsc auth status --online
gsc auth logout
gsc auth revoke --yesauth loginstarts Google sign-in in the browser.auth logoutremoves the local OAuth session. It does not revoke access at Google.auth revoke --yesrevokes the cached OAuth grant at Google and removes the local session. Use it only when you want to revoke access.
Print client configuration
Generate a configuration snippet
gsc config print --client desktop
gsc config print --client genericThe output uses absolute runtime and package paths. genericprints JSON for another MCP client; it does not edit that client's settings.
Environment variables
| Variable | Purpose |
|---|---|
| GSC_ACCESS_MODE | readonly or full; defaults to readonly |
| GSC_SITE_URLS | JSON array of exact property IDs, or all by explicit opt-in |
| GSC_AUTH_MODE | oauth or service_account; defaults to service_account |
| GSC_DATA_DIR | Local data directory; defaults to ~/.gsc-mcp |
| GSC_HISTORY | Set to 1 to enable explicit local change records and saved measurements |
| GSC_OAUTH_SECRETS_FILE | Path to your Desktop OAuth JSON file |
| GSC_OAUTH_CLIENT_ID | OAuth client ID fallback when no secrets file is set |
| GSC_OAUTH_CLIENT_SECRET | OAuth client secret fallback when no secrets file is set |
| GSC_KEY_FILE | Path to your service-account JSON file |
| GSC_SCOPES | Legacy scope mode; prefer GSC_ACCESS_MODE |
| GSC_ENABLE_WRITE | Legacy write flag. Prefer GSC_ACCESS_MODE. |
Optional setup actions
--first-query runs one small Search Analytics query for the last seven days on the first selected property. It returns up to five rows and does not request query strings. --install-skill installs the Google Search Console skill for supported agents. Setup asks before either action. --yes does not opt in to them.
Help and version
Show CLI help and installed version
gsc --help
gsc --version