Guides Commands
On this page

Command reference

A summary of the surface observed from the built CLI — the --help block below is an abridged summary, not the full output. For the authoritative text, run gsc-mcp --help against your install. There is no uninstall subcommand, no extra serve flag, and no profile management command.

Surface overview

gsc-mcp --help (abridged summary)

gsc-mcp [serve] [--profile <alias>]  Start the MCP stdio server (default)
gsc-mcp setup [options]              Guided Google sign-in and client config
gsc-mcp setup access readonly|full [--client <name>] [--dry-run] [--yes]
gsc-mcp setup enable-write [...]     Deprecated: add legacy GSC_ENABLE_WRITE=1
gsc-mcp setup disable-write [...]    Deprecated: remove legacy GSC_ENABLE_WRITE
gsc-mcp doctor [--online]            Offline check (runtime, paths, env, auth state)
gsc-mcp auth login                   Connect Google in this terminal (browser)
gsc-mcp auth status [--online]       Show session state without secrets
gsc-mcp auth logout                  Delete the local OAuth session
gsc-mcp auth revoke --yes            Revoke at Google and delete locally
gsc-mcp config print --client <name> [--profile <alias>]
gsc-mcp --version / -v               0.1.0
gsc-mcp --help / -h / help

setup

  • Flags: --client, --access readonly|full (default readonly), --site (repeatable, one identifier each, never comma-split), --all-sites, --auth shared|custom|service-account, --secrets <path>, --key-file <path>, --reauth, --force, --dry-run, --yes, --language en|es, --first-query, --install-skill, --help. --scopes and --enable-write are deprecated — use --access instead.
  • Subcommands: setup access readonly|full changes access on an existing client entry with no Google sign-in; setup enable-write and setup disable-write only touch the legacy write flag and are deprecated, never the primary path.
  • --site and --all-sites are mutually exclusive.--dry-run never calls Google. --language en|es wins over LC_ALL / LC_MESSAGES / LANG; only human copy is translated, never command names, flags, env keys, or property identifiers.

serve

  • Serve is the default: bare gsc-mcp starts the MCP stdio server. It takes only --profile <alias> — anything else fails with an unknown-flag error.
  • A named profile loads that profile’s allowlist; otherwise the server uses GSC_SITE_URLS. A missing alias errors with the fix. Datasets live 15 minutes per profile and never cross profiles.

doctor

  • Offline by default: runtime, auth_mode, site_urls, allowlist, write ops, and whether an OAuth token or service key exists — paths and booleans, never secrets.
  • doctor --online adds exactly one bounded sites.list call plus property and 29-tool catalog verification. Any other flag fails with an unknown-flag error.

auth

  • auth login connects Google in the current terminal via the browser. The MCP server never opens browsers by itself.
  • auth status shows local session state without secrets; auth status --online performs minimal Google validation and distinguishes permission problems from a disabled API or an exhausted quota.
  • auth logout deletes the local OAuth session only — service-account mode is unaffected and nothing is revoked at Google.
  • auth revoke --yes refuses without --yes, then revokes the cached token at Google and deletes it locally. Anything besides login|status|logout|revoke is rejected.

config print

  • config print --client <name> [--profile <alias>] prints one client snippet to copy. Unknown clients are rejected with the supported set: desktop, code, cursor, codex, generic.
  • config accepts only print — there is no other config subcommand.

--help and --version

  • --help, -h, and help print usage; --version and -v print 0.1.0.

Environment

VariableMeaning
GSC_AUTH_MODEoauth | service_account (default service_account)
GSC_ACCESS_MODEreadonly | full (default readonly; full enables Google writes with no further confirm)
GSC_ENABLE_WRITELegacy: =1, only when GSC_ACCESS_MODE is unset
GSC_SITE_URLSJSON array of exact property IDs, or "all" alone (explicit opt-in); legacy comma lists still read
GSC_DATA_DIRLocal state dir (default ~/.gsc-mcp)
GSC_KEY_FILEService-account JSON path
GSC_SCOPESLegacy: readonly | full, only when GSC_ACCESS_MODE is unset
GSC_OAUTH_SECRETS_FILECustom OAuth: downloaded Desktop JSON path (wins over the env vars below)
GSC_OAUTH_CLIENT_IDCustom OAuth: client ID env fallback when no secrets file is set
GSC_OAUTH_CLIENT_SECRETCustom OAuth: client secret env fallback when no secrets file is set
--yes never opts you into the first-query sample or the skill install below — each needs its own explicit flag. Skipping a prompt is not the same as consenting to an action.

First-use opt-ins

  • --first-query runs one minimal query on the first selected property: last 7 days, date breakdown, at most 5 rows, never query strings. Skipped for allow-all.
  • --install-skill installs the google-search-console-mcp skill globally through the pinned skills CLI, mapping code→claude-code, cursor→cursor, codex→codex.
  • Three server-side prompts are registered for your agent: seo_weekly_report (weekly KPIs, movers, opportunities), investigate_traffic_drop (pages/queries/segments decomposition), page_performance_review (one page plus its observed queries). A good first question: What are my quick win keywords?
  • Every response carries its coverage and limitations — analyses describe returned rows, not all searches; position is an impression-weighted average. Named errors and their fixes live under Troubleshooting.

Next