mcp-google-gsc

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

Quick install

Claude Code, one line (replace the placeholder values with your own; see Configuration for how to get them):

claude mcp add --env GOOGLE_GSC_CLIENT_ID=YOUR_CLIENT_ID --env GOOGLE_GSC_CLIENT_SECRET=YOUR_CLIENT_SECRET --env GOOGLE_GSC_REFRESH_TOKEN=YOUR_REFRESH_TOKEN --transport stdio mcp-google-gsc -- npx -y mcp-google-gsc

The server is read-only: all four tools are reads and it only asks for the webmasters.readonly scope. For unattended use, set GOOGLE_APPLICATION_CREDENTIALS to a service-account key file instead (see Mode B).

{
  "mcpServers": {
    "mcp-google-gsc": {
      "command": "npx",
      "args": ["-y", "mcp-google-gsc"],
      "env": {
        "GOOGLE_GSC_CLIENT_ID": "YOUR_CLIENT_ID",
        "GOOGLE_GSC_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "GOOGLE_GSC_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
      }
    }
  }
}

[mcp_servers.mcp-google-gsc]
command = "npx"
args = ["-y", "mcp-google-gsc"]

[mcp_servers.mcp-google-gsc.env]
GOOGLE_GSC_CLIENT_ID = "YOUR_CLIENT_ID"
GOOGLE_GSC_CLIENT_SECRET = "YOUR_CLIENT_SECRET"
GOOGLE_GSC_REFRESH_TOKEN = "YOUR_REFRESH_TOKEN"

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 (GOOGLE_APPLICATION_CREDENTIALS, or credentials_file 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 clie

... View full README on GitHub