Primitive for Google Search Console data · GSCDump

[gscdump](https://gscdump.com/)[ ≡ menu ]

[gscdump](https://gscdump.com/)

§ contents

- [1.0→NAME](#name)
- [1.2→FEATURES](#features)
- [1.5→QUERIES](#evidence)
- [2.0→SYNOPSIS](#synopsis)
- [3.0→INSTALL](#install)
- [4.0→OPTIONS](#options)
- [5.0→EXAMPLES](#examples)
- [6.0→COMPATIBILITY](#compat)
- [7.0→SEE ALSO](#seealso)

§ elsewhere

- [›Tools](https://gscdump.com/tools)
- [›Learn](https://gscdump.com/learn-google-search-console)
- [›MCP](https://gscdump.com/mcp)
- [›Pricing](https://gscdump.com/pricing)

[GitHub](https://github.com/harlan-zw/gscdump)

§ 1.0 · gscdump(1)

# AI Search Consoleprimitive for agents.

gscdump is an open-source tool that dumps your Google Search Console data, providing native SQL for deep analysis and insight into your organic search data.

1.2/FEATURES

Everything an agent needs to read your Search Console data, without row caps, service accounts, or sending bytes anywhere but your disk.

FIG. 1.2 · feature index6 cells

1.2.1 ### No row cap

Paginates past GSC's 25k-row API limit. Up to 450 days of impressions, clicks, and positions on disk.

1.2.2 ### MCP-ready

One JSON block in your config. Works with Claude, Cursor, Codex, and Windsurf out of the box.

1.2.3 ### 27 analyzers

Striking-distance, cannibalization, decay, intent atlas, change-point — pre-rolled, typed output.

1.2.4 ### Local-first

DuckDB + Parquet on disk. Read-only OAuth scope. Nothing of yours leaves the machine.

1.2.5 ### Typed query API

One typed query interface for the local store. Add --live for a fresh hit against the GSC API.

1.2.6 ### Open source

npm install -g @gscdump/cli. MIT-licensed. No service-account dance, no hosted lock-in.

1.5/ADVANCED QUERIES

Four analyzers run live against [nuxtseo.com](https://nuxtseo.com)'s Search Console data. Every panel below is real output, regenerated daily. Hover anything to inspect; this is the same render the CLI's `analyze` command produces.

LIVE · nuxtseo.com · 4 analyzersupdated 46d ago

1.1CANNIBALIZATIONnuxt seo · 5 URLs

force-graph · self-competing URLs

//pro/docs/nuxt-seo…nuxt-seo-kit/docs/nuxt-seo…introduction/releases/docs/og-image…installation/docs/sitemap/…installation/learn-seo/vue/spa/learn-seo/nuxt/learn-seo/vue/learn-seo/pre-launch-warmup/learn-seo/nux…aunch-warmup/docs/robots/a…nced/content/docs/robots/releases/v4/docs/robots/g…installation/docs/robots/g…how-it-works/learn-seo/vue…he-3-pillars/docs/sitemap/…stomising-ui/docs/sitemap/api/config/docs/sitemap/releases/v3/learn-seo/nux…rs/meta-tags #### Worst offenders

1. 49nuxt seo5 urls
2. 41nuxt og image3 urls
3. 30nuxt sitemap2 urls
4. 0is nuxt js good for seo3 urls
5. 0is nuxt.js good for seo5 urls
6. 0nuxt js good for seo4 urls
7. 0nuxt js for seo10 urls
8. 0seo warmup2 urls

click a query to highlight its URLs

1.2INTENT ATLAS36 clusters · 841 keywords

treemap · query clusters by impressions

schema + validator79 kw · 197.6kchecker + schema37 kw · 61.8kchecker + meta98 kw · 29.2kcheck + meta41 kw · 16.7kcheck + schema42 kw · 16.5ksitemap + validator22 kw · 14.9kchecker + sitemap23 kw · 14.0kschema + tool12 kw · 11.6krobots + txt42 kw · 10.8kdata + tool12 kw · 10.8kschema + tester5 kw · 10.6kschema + test15 kw · 9.6kschema.org + validator7 kw · 9.0knuxt + seo19 kw · 8.5kmeta + robots32 kw · 8.0kchecker + title28 kw · 7.8kcheck + seo17 kw · 6.8kseo + spa12 kw · 6.7k

Hover a tile to inspect its cluster. Each tile is a token-cooccurrence cluster. Brighter = higher CTR, darker = better position. Tile size = total impressions.

1.3QUERY MIGRATION24 flows · 1383 impr absorbed

sankey · queries that swapped pages

lost from (prev period)gained by (current period)

…started/introduction/…rendering/pagination…started/installation…guides/canonical-url…es/using-the-modules…n-guide/nuxt-seo-kit…started/introduction…/guides/default-meta…started/introduction…vanced/images-videos/learn-seo/nuxt/releases/tools/learn-seo/nuxt/learn-seo/checklist…nuxt-seo/releases/v5/…/sitemap/releases/v4…/guides/how-it-works…es/using-the-modules

Hover an edge to see the migrating queries. Edges are matched via exact equality or DuckDB's `levenshtein()` ≤ 2 — queries that almost survived but landed on a different URL.

1.4POSITION VOLATILITY14 pages · 14 days

heatmap · ranking instability per page/day

| page | 03-29 | 03-30 | 03-31 | 04-01 | 04-02 | 04-03 | 04-04 | 04-05 | 04-06 | 04-07 | 04-08 | 04-09 | 04-10 | 04-11 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| …getting-started/introduction μ=41.88 · max=51.73 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| …migration-guide/nuxt-seo-kit μ=39.49 · max=62.03 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| /learn-seo/checklist μ=37.33 · max=58.64 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| …seo/guides/using-the-modules μ=35.24 · max=46.56 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| …getting-started/installation μ=33.61 · max=48.94 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| /releases μ=32.30 · max=41.62 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| …ntrolling-crawlers/meta-tags μ=32.12 · max=58.87 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| /learn-seo/vue μ=29.51 · max=34.95 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| /learn-seo/nuxt μ=29.31 · max=60.61 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| /tools μ=28.62 · max=44.70 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| …/robots/guides/robot-recipes μ=28.53 · max=38.28 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| …cs/sitemap/advanced/loc-data μ=27.61 · max=52.85 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| /tools/domain-rankings μ=27.55 · max=34.64 |  |  |  |  |  |  |  |  |  |  |  |  |  | |
| …/guides/nuxt-config-seo-meta μ=25.50 · max=42.43 |  |  |  |  |  |  |  |  |  |  |  |  |  | |

analyzers · 4 of 21 shown`gscdump analyze --help`

2.0/SYNOPSIS

gscdump syncs up to four-hundred-and-fifty days of Search Console data into a local DuckDB store; twenty-seven analyzers ship with the CLI; the bundled MCP server exposes the same store to any agent that speaks the protocol. Read-only, credentials encrypted at rest, no data leaves your machine.

SHELL · the entire CLI surfacecmd · 5 lines

```
gscdump init                                  # oauth round-trip with google
gscdump sync     --site <url>                # 16 months to local parquet
gscdump query    --site <url> [--live]       # typed query, optional live api
gscdump analyze  <tool> --site <url>     # 27 built-in seo analyzers
gscdump mcp                                   # run local mcp server
```

local · duckdb + parquet`@gscdump/cli` on npm

3.0/INSTALL

One npm install, one OAuth round-trip. Data lives in a local DuckDB/Parquet store; nothing of yours leaves the machine.

SHELL · install + first-run

```
# 1. install
$ npm install -g @gscdump/cli

# 2. authorise (browser opens)
$ gscdump init
```

[→ npm package](https://www.npmjs.com/package/@gscdump/cli) [Full install guide](https://gscdump.com/mcp)

works in:Claude Desktop·Claude Code·Cursor·Codex·Windsurf

- [!]Read-only access. We never write to your Google account.
- [*]OAuth scoped to Search Console. You can revoke at any time.
- [?]Tokens encrypted at rest with per-account keys. Open source codebase.
- [§]No tracking, no ads, no third-party cookies. DPA on request.

4.0/OPTIONS

gscdump separates the boring half from the interesting half. _read_ covers the GSC primitives — sync, query, inspect, MCP — and is the open-source CLI. _analyze_ dispatches to twenty-seven built-in analyzers ranging from simple SEO heuristics to statistical change-point detection. Twenty-seven analyzers, three families.

4.1

## READ

cli + mcp · open source

Sync up to 450 days of Google Search Console data into a local DuckDB/Parquet store. Run typed queries against it. Expose the same store to any MCP-compatible agent. Cross-process locking; idempotent sync; pagination walks past GSC's 25k-row cap.

→init

OAuth round-trip with Google; credentials stored locally.

→sites

List verified properties on the connected account.

→sitemaps

List/manage sitemaps for a site.

→inspect

URL Inspection API — live indexing status.

→sync

Pull GSC into the local store (default 3 days; --full = 450).

→query

Typed query over the local store; --live for fresh API.

→mcp

Run the local MCP server over stdio.

4.2

## ANALYZE

analyst · 27 tools

Run any of 27 built-in analyzers against the local store. Three families: core SEO (striking-distance, cannibalization, movers, decay, zero-click, brand, dark-traffic, device-gap), statistical (CTR anomalies, CTR curve, position volatility, position distribution, change-point, STL decompose, survival, Bayesian CTR), and structural (long-tail, intent-atlas, clustering, concentration, query migration, seasonality, trends, content-velocity, keyword-breadth, bipartite-pagerank).

→striking-distance

Queries ranked positions 4–20 with impression weight.

→cannibalization

URLs competing for the same query intent.

→movers

Largest position deltas, weighted by traffic.

→decay

Keywords losing ground over the trailing window.

→ctr-anomaly

Outlier CTRs vs the rolling baseline.

→change-point

Statistical break-points in time series.

→intent-atlas

Map queries to intent clusters.

→…

20 more — see analyze list for the full set.

Open-source CLI; `@gscdump/cli` on npm. Analyzers ship in `@gscdump/analysis`. Storage engine is `@gscdump/engine`. [See github(1)](https://github.com/harlan-zw/gscdump).

5.0/EXAMPLES

§ 5.1 · sync, query, analyze

### Pull GSC into a local store, then dig.

SHELL · gscdump sync + analyzesession

```
# default sync — last 3 days, idempotent
$ gscdump sync --site https://example.com
▶ syncing 3 days · 4 tables
  pages      ━━━━━━━━━━━━   5,412 rows
  keywords   ━━━━━━━━━━━━   1,388 rows
  countries  ━━━━━━━━━━━━     217 rows
  devices    ━━━━━━━━━━━━       9 rows
✓ done · 512 KB on disk · 1.4s

# run an analyzer over the local store
$ gscdump analyze striking-distance --site https://example.com

  KEYWORD                          POS    IMPR     CTR
  ─────────────────────────────    ────   ──────   ─────
  nuxt seo meta tags                8.7   2,012   1.10%
  nuxt content auth                 9.2   4,128   0.40%
  nuxt sitemap xml                 11.4   1,847   0.22%
  vue 3 composition api            12.1   3,605   0.31%
  …                                                  18 more
```

local · duckdb + parquet27 analyzers

Sync is idempotent. `--full` backfills 450 days; `--start --end` for a custom window. Pagination walks past GSC's 25k-row cap automatically.

§ 5.2 · expose to an agent

### One JSON block, the agent sees the store.

FILE  ~/.config/claude/claude_desktop_config.json

```
{
  "mcpServers": {
    "gscdump": {
      "command": "npx",
      "args": ["@gscdump/cli", "mcp"]
    }
  }
}
```

stdio transport · local mcp7 lines

- ▸"What pages lost traffic this week?"
- ▸"Find keywords in striking distance (position 4–20)."
- ▸"Which queries have cannibalization issues?"
- ▸"Compare this month vs last month for /blog/ pages."

6.0/COMPATIBILITY

Reading GSC from an agent is now table stakes. OSS MCPs fragment over a dozen self-host packages. SEO Gets is Claude-only and dashboard-led. gscdump is the hosted primitive built for any agent.

TABLE · feature comparison4 vendors

| feature | gscdump | oss mcps | seo gets | gsc ui |
| --- | --- | --- | --- | --- |
|  |  | |
| 16mo stored history, no row cap | ■ | · | ■ | · |
| Hosted MCP for any agent | ■ | self | claude | · |
| Pre-rolled deep analyses | ■ | · | partial | · |
| URL Inspection at scale | ■ | partial | · | manual |
| Hosted, no install | ■ | · | ■ | ■ |
| Free tier | ■ | ■ | · | ■ |

■ supported · · absent · partial / self / claude / manualfig. 6.1

7.0/SEE ALSO

<dl>

<dt>mcp(1)</dt>
<dd>[Install guide for Claude, Cursor, Codex, Windsurf](https://gscdump.com/mcp)</dd>

<dt>pricing(7)</dt>
<dd>[Free tier & credit packs](https://gscdump.com/pricing)</dd>

<dt>tools(7)</dt>
<dd>[Hosted analyses you can run now](https://gscdump.com/tools)</dd>

<dt>learn(7)</dt>
<dd>[A primer on Google Search Console](https://gscdump.com/learn-google-search-console)</dd>

<dt>github(1)</dt>
<dd>[Source · MIT · open issues](https://github.com/harlan-zw/gscdump)</dd>

</dl>

FIG. 7.1 · read flowschematic

```
  ┌─────────────┐
  │  AI agent   │
  │  (claude…)  │
  └──────┬──────┘
         │ MCP
         ▼
  ┌─────────────┐
  │  gscdump    │
  │  /mcp       │  ◀── api key
  └──────┬──────┘
         │ oauth
         ▼
  ┌─────────────┐
  │ Search      │
  │ Console API │
  └─────────────┘
```

read mode · 1 hop~120ms p50

Free for any agent. Bring your own OAuth.

Sign in with Google, drop the key into your MCP config, query sixteen months of Search Console from the tool you already use.

[→ Get an API key](https://gscdump.com/auth/google) [MCP install guide](https://gscdump.com/mcp)