Google Gsc MCP server

mcp-google-gsc

MCP server for Google Search Console -- search analytics, URL inspection, and site management via Claude.

Features

• Search Analytics -- Query clicks, impressions, CTR, and position with flexible dimension filters (query, page, device, country, date)
• URL Inspection -- Check indexing status, mobile usability, and rich results for any URL
• Site Listing -- List all verified Search Console properties accessible to your authenticated account (OAuth user or service account)
• Multi-Client Support -- Manage multiple GSC properties with per-directory config mapping

Installation

From npm

npm install mcp-google-gsc

From source

git clone https://github.com/mharnett/mcp-search-console.git
cd mcp-google-gsc
npm install
npm run build

Configuration

Security: Never share your .mcp.json file or commit it to git -- it may contain API credentials. Add .mcp.json to your .gitignore.

mcp-gsc supports two authentication modes. Pick whichever fits your setup. Neither requires any file living at a hardcoded machine-local path -- credentials come from environment variables (or a config.json you create).

Which mode to use:

• Service Account (Mode B) -- recommended for unattended / server / headless use. A service account has no interactive login to expire or re-consent, so it is the right fit for always-on deployments. The one setup requirement is that the service account's email must be granted access on each Search Console property you want to query (see Mode B).
• User OAuth (Mode A) -- for personal / interactive use, where you want to authorize with your own Google login.

Precedence when both are configured: if a service-account keyfile is explicitly set (GOOGLEAPPLICATIONCREDENTIALS, or credentialsfile in config.json), it wins** over any OAuth refresh token or stored OAuth credentials. If neither is configured, the server fails loudly at startup with an onboarding message rather than silently guessing -- there is no machine-local default and no silent runtime failover between modes.

Mode A: User OAuth (bring your own Google account)

Use this if you want to authorize with your own Google login (the account that has Search Console access). Best for personal / interactive use.

1. In the Google Cloud Console, create an OAuth 2.0 Client ID of type Desktop app and enable the Search Console API. (For a Desktop-app client, Google accepts any http://localhost loopback redirect -- you do not need to pre-register a port.)
2. Export your client credentials:

export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
   export GOOGLE_GSC_CLIENT_SECRET=...

1. Mint a refresh token (opens your browser, uses PKCE + access_type=offline):

node get-refresh-token.cjs

Do not redirect this command's stdout to a shared log -- it prints the refresh token to stdout by design.

1. Copy the printed line into your environment:

export GOOGLE_GSC_REFRESH_TOKEN=...

The server reads GOOGLEGSCCLIENTID, GOOGLEGSCCLIENTSECRET, and GOOGLEGSCREFRESH_TOKEN from the environment at runtime.

Alternatively, run the guided helper npx mcp-gsc-auth, which performs the same PKCE OAuth flow, lets you pick a default Search Console property, and writes the result to a per-user credentials file.

Mode B: Service Account (recommended for unattended / server use)

Use this for server / headless / always-on contexts -- it is the recommended path when no human is present to complete or refresh an interactive login.

Shortened. The full README is on GitHub.