Change impact and local history

Compare observed Search Console metrics around a change. History is optional and local; the comparison is descriptive, not causal.

Enable history

Set GSC_HISTORY=1 in the MCP server environment and restart your client to record, list or delete changes and save snapshots. This is independent of exports and adds no Google scope. Analysis with a transient change needs no history and writes no files.

Record a change

Use action=record with a date and 1–100 URLs. The label and description are optional; an optional idempotencyKey avoids duplicate records for the same request.

{
  "siteUrl": "https://example.com/",
  "action": "record",
  "change": {
    "date": "2026-01-15",
    "label": "Update article",
    "urls": [
      "https://example.com/article"
    ]
  },
  "idempotencyKey": "example-article-update"
}

Analyze a change

Use either an inline change or a saved changeId, not both. Up to three explicit controlUrls must differ from changed URLs. Batch size defaults to one, maximum three. Default windows are 28 days before, seven transition days including the change day, and 28 days after. A still-incomplete after window is preliminary; no extrapolation is made. Saved snapshots require saveSnapshot=true, a saved changeId, and history enabled. Saving occurs on the explicitly requested call; do not assume a snapshot represents only a completed session.

{
  "siteUrl": "https://example.com/",
  "action": "analyze",
  "change": {
    "date": "2026-01-15",
    "urls": [
      "https://example.com/article"
    ]
  }
}

{
  "siteUrl": "https://example.com/",
  "action": "analyze",
  "changeId": "replace-with-saved-change-id",
  "saveSnapshot": true
}

List and delete

Use action=list to list changes for the current profile and property. Add changeId to retrieve a change and its snapshots. action=delete with changeId removes the record and its snapshots; it is an explicit local deletion. Replace the example ID with a returned ID.

{
  "siteUrl": "https://example.com/",
  "action": "list"
}

{
  "siteUrl": "https://example.com/",
  "action": "list",
  "changeId": "replace-with-saved-change-id"
}

{
  "siteUrl": "https://example.com/",
  "action": "delete",
  "changeId": "replace-with-saved-change-id"
}

Read saved snapshots

When snapshots exceed 1 MiB, list with changeId returns snapshotChunk and nextCursor. Continue action=list with the same property and change ID, passing that cursor. Group chunks by snapshotId, decode each base64 block, concatenate bytes in offset order, then decode UTF-8 and parse JSON. Chunks are up to 24 KiB and are transmitted as raw JSON bytes without validating the large snapshot. These persistent-history cursors differ from the 15-minute audit-session cursor and the dataset cursor; a changed or missing file invalidates a cursor.

Storage and privacy

Records and snapshots are stored under GSC_DATA_DIR/history, or ~/.gsc-mcp/history by default, isolated by profile and property. They contain metrics, observed queries, parameters and coverage, not tokens, credentials or full HTML. The cumulative limit is 100 MiB and there is no automatic purge. Uninstalling the package alone does not delete history. Deleting the local data directory permanently removes history along with credentials and profiles. Cancellation after deletion starts can leave it partially applied.

Related guides

• Audit sessions and coverage →
• Privacy and data flow →
• Remove local data →