gsc-coverage-mcp

A Google Search Console MCP server for Claude (or any MCP client) that pulls every row Google will give you and tells the model how much of the picture those rows cover.

Why

The Search Analytics API returns 1,000 rows by default and at most 25,000 per request. Many GSC connectors make one request and stop. The model does correct math on that first slice and writes a report that reads as if it covered the whole site.

Even a full pull isn't every query. Google drops anonymized and rare queries, so query-level rows never add up to the property totals. On a small site it is normal for query rows to cover only half of all clicks.

That's how an audit goes wrong while every number in it checks out: "dead" pages that actually have impressions, cannibalization that was missed, content gaps for pages you already have, and "lost rankings" that are just two pulls with different coverage.

This server fixes the two parts a connector can fix:

1. Pagination. search_analytics walks startRow in 25,000-row pages until Google runs out of rows, up to a maxRows safety cap you control.

2. A coverage report on every pull. Each response includes a coverage block, so the model has to see what it is working from before it writes recommendations.

Related MCP server: Google Search Console MCP Server

What a response looks like

{
  "coverage": {
    "window": { "startDate": "2026-09-01", "endDate": "2026-09-30", "type": "web", "dataState": "final" },
    "dimensions": ["query"],
    "rowsReturned": 3412,
    "pagesFetched": 1,
    "apiExhausted": true,
    "truncated": false,
    "propertyTotals": { "clicks": 1980, "impressions": 412300 },
    "rowSums": { "clicks": 1104, "impressions": 301877 },
    "clickCoveragePct": 55.8,
    "impressionCoveragePct": 73.2,
    "notes": [
      "Query rows never add up to property totals: Google drops anonymized and rare queries. The gap comes from Google's privacy filtering, and the missing clicks still belong to pages you have.",
      "Missing from these rows is not the same as zero. Check any absent URL or query with a direct filter before calling it lost or invisible."
    ]
  },
  "file": "/tmp/gsc-coverage-mcp/pull-1761650000000.csv",
  "preview": [{ "query": "example query", "clicks": 84, "impressions": 2210, "ctr": 3.8, "position": 4.12 }]
}

(Illustrative numbers.)

Large pulls are written to CSV or JSON, and only a preview comes back inline. That keeps 80,000 rows out of the model's context window while still giving it the full file to work with.

Tools

search_analytics inputs:

Setup

Requires Node 18+.

git clone https://github.com/Boston617Delta/gsc-coverage-mcp.git
cd gsc-coverage-mcp
npm install

Credentials

Either of these works:

• Service account (recommended for anything scheduled). Create a service account and a JSON key, then add the service account's email as a user on each Search Console property (Restricted is enough). Point GOOGLE_APPLICATION_CREDENTIALS at the key. Service accounts don't hit the periodic re-authentication that user logins do, so scheduled jobs keep running.

• Application Default Credentials. gcloud auth application-default login with the https://www.googleapis.com/auth/webmasters.readonly scope. This works for interactive use, but if your Google Workspace enforces Google Cloud session control, expect to log in again every few days.

If your organization blocks service account keys (iam.disableServiceAccountKeyCreation, on by default for newer Google Cloud orgs), an org policy admin can lift it for a single project:

gcloud resource-manager org-policies disable-enforce iam.disableServiceAccountKeyCreation --project=YOUR_PROJECT

Keep the key file out of version control, readable only by you (chmod 600).

Claude Code

claude mcp add gsc-coverage \
  --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \
  -- node /path/to/gsc-coverage-mcp/src/index.js

Claude Desktop

{
  "mcpServers": {
    "gsc-coverage": {
      "command": "node",
      "args": ["/path/to/gsc-coverage-mcp/src/index.js"],
      "env": { "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json" }
    }
  }
}

Codex

The Codex CLI, IDE extension and desktop app share ~/.codex/config.toml. Add:

[mcp_servers.gsc-coverage]
command = "node"
args = ["/path/to/gsc-coverage-mcp/src/index.js"]
tool_timeout_sec = 180

[mcp_servers.gsc-coverage.env]
GOOGLE_APPLICATION_CREDENTIALS = "/path/to/service-account.json"

Or from the CLI:

codex mcp add gsc-coverage \
  --env GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json \
  -- node /path/to/gsc-coverage-mcp/src/index.js

Codex stops a tool call after 60 seconds by default, and a pull of 100,000 rows can take longer than that, so set tool_timeout_sec in the config. If the desktop app can't start the server, replace node with the full path that which node prints.

What it can't fix

• Anonymized queries are gone. Google withholds them before any connector, warehouse or export sees the data. The coverage block measures that gap so you can report it.

• Google's own row limits still apply. Google documents a ceiling of about 50,000 rows per day, per property, per search type for page and query breakdowns. For very large sites, use the Bulk Data Export to BigQuery.

• Historical rows include dead URLs. GSC still reports pages you removed months ago. Check status codes, redirects, canonicals and indexability on the live site before recommending work on any URL.

A checklist to pair with it

Before trusting any LLM output built on GSC data:

1. Request every row, and confirm truncated is false.

2. Read clickCoveragePct. Page-level rows should land close to the property totals, while query-level rows fall short by however much Google anonymized.

3. Treat missing as unknown, not zero. Filter for the specific URL or query before calling it lost.

4. Use the same dimensions, filters and window logic for both sides of any comparison.

5. Check every recommended URL on the live site.

6. Put the date range, dimensions, row count and coverage in the deliverable.

Development

npm test

Tests use a fake Search Console client, so no credentials are needed.

License

MIT