@theethosteam/gsc-mcp

Read + write MCP server and CLI for Google Search Console — Search Analytics (clicks/impressions/CTR/position), Sitemaps (list/submit/delete), Sites (list/add/delete), and URL Inspection — authenticated over OAuth (no service account). Runs via npx, identically locally or in a cloud session, because auth is a refresh token in env vars.

Built on the same pattern as the GA4 + GTM MCPs: one shared core/, exposed as both an MCP server (mcp.ts) and a commander CLI (cli.ts), run directly with tsx (no build step). Includes a generic raw tool so every Search Console API method is reachable.

Why OAuth, not a service account

Search Console (like GA4/GTM) ties access to a Google account. OAuth acts as you, the verified property owner — nothing extra has to be granted. This needs its own refresh token (the webmasters scope), separate from the GA4 token, even if it reuses the same OAuth client id/secret.

One-time setup

1. Enable the Google Search Console API in your Google Cloud project.
2. OAuth client: reuse your existing Desktop app client (same one as GA4/GTM is fine) — note the client id + secret.
3. Mint a refresh token (no local server needed):

   GSC_OAUTH_CLIENT_ID=… GSC_OAUTH_CLIENT_SECRET=… npx -y @theethosteam/gsc-mcp gsc auth:url
   # open the URL, approve, copy the ?code=… from the localhost redirect that fails to load
   GSC_OAUTH_CLIENT_ID=… GSC_OAUTH_CLIENT_SECRET=… npx -y @theethosteam/gsc-mcp gsc auth:exchange <code>

Env vars

GSC_OAUTH_CLIENT_ID · GSC_OAUTH_CLIENT_SECRET · GSC_OAUTH_REFRESH_TOKEN · GSC_SITE_URL (optional default property).

Property format: Domain property → sc-domain:example.com. URL-prefix property → https://example.com/ (trailing slash).

Connect to Claude

Local (Claude Code CLI), available in every project:

claude mcp add gsc --scope user \
  -e GSC_OAUTH_CLIENT_ID=… -e GSC_OAUTH_CLIENT_SECRET=… -e GSC_OAUTH_REFRESH_TOKEN=… \
  -e GSC_SITE_URL=sc-domain:example.com \
  -- npx -y @theethosteam/gsc-mcp

Cloud (Claude Code on the web): add the server to the repo's .mcp.json with env via ${VAR}, then reload:

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@theethosteam/gsc-mcp"],
      "env": {
        "GSC_OAUTH_CLIENT_ID": "${GSC_OAUTH_CLIENT_ID}",
        "GSC_OAUTH_CLIENT_SECRET": "${GSC_OAUTH_CLIENT_SECRET}",
        "GSC_OAUTH_REFRESH_TOKEN": "${GSC_OAUTH_REFRESH_TOKEN}",
        "GSC_SITE_URL": "${GSC_SITE_URL}"
      }
    }
  }
}

Tools

list_sites · get_site · list_sitemaps · get_sitemap · query_search_analytics · inspect_url · health_check · submit_sitemap · delete_sitemap · add_site · delete_site · raw

Destructive tools (delete_sitemap, delete_site) require confirm: true.

CLI (handy for testing)

npx -y @theethosteam/gsc-mcp gsc sites
npx -y @theethosteam/gsc-mcp gsc submit-sitemap https://example.com/sitemap.xml -s sc-domain:example.com
npx -y @theethosteam/gsc-mcp gsc query -s sc-domain:example.com -d query --limit 10
npx -y @theethosteam/gsc-mcp gsc inspect https://example.com/ -s sc-domain:example.com

License

MIT