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 --version

Connect Google and a client

Example: connect Cursor with read-only Quick Connect

gsc setup --client cursor --auth shared --access readonly

Setup 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-account chooses Quick Connect, your OAuth client, or a service account.
  • --access readonly|full selects 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 all alone or --all-sites to 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-run previews setup without Google sign-in or client changes. --reauth starts a fresh OAuth sign-in. --verbose prints the full detail.
  • --force or --yes skips the client configuration confirmation. --yes never opts in to writes, the sample query, or the skill install. --language en|es sets setup language.

Change an existing access mode

Change a client to read-only

gsc setup access readonly --client cursor

Use 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

New setups should use --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 reporting

MCP 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 --online

The 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 --check

Manage 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 --yes
  • auth login starts Google sign-in in the browser.
  • auth logout removes the local OAuth session. It does not revoke access at Google.
  • auth revoke --yes revokes 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 generic

The output uses absolute runtime and package paths. genericprints JSON for another MCP client; it does not edit that client's settings.

Environment variables

VariablePurpose
GSC_ACCESS_MODEreadonly or full; defaults to readonly
GSC_SITE_URLSJSON array of exact property IDs, or all by explicit opt-in
GSC_AUTH_MODEoauth or service_account; defaults to service_account
GSC_DATA_DIRLocal data directory; defaults to ~/.gsc-mcp
GSC_HISTORYSet to 1 to enable explicit local change records and saved measurements
GSC_OAUTH_SECRETS_FILEPath to your Desktop OAuth JSON file
GSC_OAUTH_CLIENT_IDOAuth client ID fallback when no secrets file is set
GSC_OAUTH_CLIENT_SECRETOAuth client secret fallback when no secrets file is set
GSC_KEY_FILEPath to your service-account JSON file
GSC_SCOPESLegacy scope mode; prefer GSC_ACCESS_MODE
GSC_ENABLE_WRITELegacy 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

Next