Skip to main content
Glama

Google Search Console Agent Pro (GSC Pro)

Python License: MIT CI MCP PRs Welcome

The Advanced Autonomous Google Search Console Intelligence Engine & AI Agent Toolkit

Empirical property-level CTR curves • Clicks at Stake ROI prioritization • Quota-aware URL inspection triage • Closed-loop 28-day change tracking

Quickstart • Why GSC Pro (Comparison) • Terminal Preview • CLI Commands • AI Agent Integration • Architecture


🚀 The Advanced Evolution of google-search-console-agent

Standard Google Search Console agents (such as arcbaslow/google-search-console-agent) provide helpful query routing and basic reporting. However, real-world SEO engineering quickly reveals critical roadblocks:

  1. Unverified Static Curves: Standard tools rely on an arbitrary, unverified static CTR heuristic (e.g. Rank 1 = 30%, Rank 2 = 15%) that cannot accurately evaluate unique niches, brand dominance, or modern SERP layouts with AI Overviews.

  2. Subjective Severity Flags: Findings are tagged with generic rules ("High / Medium / Low") without quantifying how much traffic or revenue is actually at stake.

  3. Audits Completely Skip URL Inspection: Because Google imposes a strict 2,000 requests/day per property quota, standard full-site audits skip inspection entirely, missing canonical conflicts and indexation drops.

  4. Stateless Execution: Traditional tools run once and forget everything, unable to remember yesterday's data or store long-tail query performance.

  5. Passive One-Way Recommendations: Standard tools output a report and stop. They cannot tell you if the title tag or schema change you deployed 3 weeks ago actually lifted traffic.

google-search-console-agent-pro was built specifically to solve these gaps.


Related MCP server: Google Search Console MCP Intel Engine

🌟 Why GSC Pro? (The Advanced Difference)

Area

Standard GSC Agent (arcbaslow/google-search-console-agent)

GSC Agent Pro (gsc-pro)

CTR Curve Provenance

Static composite curve with unverified provenance; acknowledged heuristic

Empirical Property-Level Curves: Computes your site's actual median (P25, P50, P75) CTR per rank position (1–20), automatically isolating brand queries.

Opportunity Scoring

Generic severity (Low/Med/High) based on arbitrary rank delta

"Clicks at Stake" ROI Formula: Quantifies exact traffic upside: $$\Delta\text{Clicks} = \text{Impressions} \times (\text{Target CTR} - \text{Observed CTR})$$ Ranks tasks by incremental monthly clicks gained.

URL Inspection in Audits

Omitted completely from audits; user must manually guess and run URLs one-by-one

Smart Quota-Aware Triage Engine: Scores all site URLs by impression volume and traffic decay, safely inspecting the top vulnerable candidates within Google's 2,000/day limit.

Data Persistence

Ephemeral outputs; no persistent database or history

Persistent SQLite Engine (~/.gsc_pro/cache.db): Stores full audit snapshots, query trends, and long-tail performance data locally.

Closed-Loop Accountability

Passive reporting; stops at writing recommendations

28-Day Closed-Loop Impact Tracker: Log on-page interventions (gsc-pro log-change) and measure the statistical 28-day pre vs. post traffic delta (gsc-pro verify-impact).

Google Authentication

Requires complex manual OAuth client setup or credentials files

Zero-Config Google ADC: Single command (gcloud auth application-default login) with automatic token refresh; no GCP console headaches.

AI Assistant Workflows

Router MCP + markdown scripts

FastMCP Server + Tool Registry: Native tools for Cursor, Claude Code, Antigravity, and Codex.


🖥️ Terminal Preview

┌──────────────────────────────────── GSC Intelligence Summary ────────────────────────────────────┐
│ Google Search Console Pro Audit                                                                  │
│ Site: sc-domain:example.com | Total Clicks: 28,450 | Clicks at Stake: +6,320 clicks/mo           │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
                     Top Prioritized Opportunities (Ranked by Clicks at Stake)                      
┌──────┬─────────────────────────┬────────┬───────────┬───────────┬──────────────────┬────────────────────────────────────────────────────────┐
│ #    │ Query                   │  Rank  │  Observed │  Expected │  Clicks at Stake │ Actionable Prescription                                │
├──────┼─────────────────────────┼────────┼───────────┼───────────┼──────────────────┼────────────────────────────────────────────────────────┤
│ 1    │ best enterprise gsc     │  3.1   │      2.1% │     11.4% │           +1,860 │ SERP snippet rewrite (title tag hook & meta summary)   │
│ 2    │ automated seo audit     │  4.2   │      1.8% │      8.2% │           +1,280 │ Content depth expansion & search intent alignment      │
│ 3    │ ctr optimization agent  │  2.0   │      5.4% │     16.2% │             +950 │ SERP snippet rewrite (add rich schema & click hook)    │
│ 4    │ quota safe url inspect  │  8.4   │      0.8% │      2.9% │             +420 │ Internal link equity injection & topical cluster depth │
└──────┴─────────────────────────┴────────┴───────────┴───────────┴──────────────────┴────────────────────────────────────────────────────────┘

⚡ 1-Minute Quickstart

1. Install

Install via uv (recommended for speed) or pip:

# With uv (recommended)
uv tool install google-search-console-agent-pro

# Or standard pip
pip install google-search-console-agent-pro

2. Authenticate (Zero Config)

No Google Cloud Console project setup or client_secrets.json required. Authenticate using Google Application Default Credentials:

gcloud auth application-default login --scopes=https://www.googleapis.com/auth/webmasters.readonly,https://www.googleapis.com/auth/webmasters

3. Run Your First Audit

# Run full empirical audit
gsc-pro audit sc-domain:example.com

# Save clean GitHub Flavored Markdown report
gsc-pro audit sc-domain:example.com --format markdown -o audit.md

🛠️ CLI Commands Reference

🔍 Comprehensive Empirical Audit

Pulls search analytics, builds empirical property-level curves, calculates Clicks at Stake, and triages top vulnerable URLs:

gsc-pro audit sc-domain:example.com --days 28 --inspect-top 25

📈 Property-Level Empirical CTR Curve

Calculates the 25th, 50th (median), and 75th percentile CTRs for your domain across positions 1–20, automatically filtering out brand searches:

gsc-pro ctr sc-domain:example.com --brand "mybrand"

🎯 "Clicks at Stake" Opportunity Prioritization

Ranks all queries strictly by quantifiable monthly traffic left on the table:

gsc-pro prioritize sc-domain:example.com --min-impressions 50 --top 20

🛡️ Quota-Aware URL Inspection Triage

Scores and inspects your top decaying and unindexed pages while guaranteeing Google's 2,000 requests/day per property quota is never exceeded:

# Triage top vulnerable pages
gsc-pro inspect sc-domain:example.com --triage-top 25

# Or inspect a single URL
gsc-pro inspect sc-domain:example.com --url https://example.com/pricing

🔄 Closed-Loop Change Tracking & Impact Verification

Log on-page updates (title tags, meta descriptions, schema markup, content depth) and mathematically evaluate the 28-day performance outcome:

# 1. Record an on-page update
gsc-pro log-change sc-domain:example.com https://example.com/guide --type title --note "Rewrote title hook for CTR"

# 2. Verify 28-day outcome delta (clicks, impressions, rank)
gsc-pro verify-impact sc-domain:example.com 1

🤖 AI Agent Integration (MCP)

gsc-pro includes a built-in Model Context Protocol (MCP) server ready for Claude Code, Cursor, and Google Antigravity.

Claude Code

claude mcp add gsc-pro -- gsc-pro mcp

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "gsc-pro": {
      "command": "gsc-pro",
      "args": ["mcp"]
    }
  }
}

Google Antigravity (~/.gemini/settings.json)

{
  "mcpServers": {
    "gsc-pro": {
      "command": "gsc-pro",
      "args": ["mcp"]
    }
  }
}

Available MCP Tools

  • gsc_list_sites(): List all verified Search Console properties.

  • gsc_audit(site_url, days=28): Full empirical audit with Clicks at Stake, intent segmentation, and URL triage.

  • gsc_ctr_curve(site_url, days=28): Empirical distribution (P25, P50, P75) per rank position.

  • gsc_prioritize_opportunities(site_url, min_impressions=50): Top traffic opportunities ranked by quantifiable Clicks at Stake.

  • gsc_inspect_triage(site_url, max_inspect=20): Quota-safe URL inspection triage for decaying and high-impression pages.

  • gsc_log_change(site_url, target, change_type, note): Record on-page fixes.

  • gsc_verify_impact(site_url, change_id): Measure 28-day pre vs post outcome lift.


🏛️ Architecture

gsc_pro/
├── auth.py          # Google Application Default Credentials (ADC) manager
├── client.py        # Resilient Search Console API client with retry backoff
├── ctr_model.py     # Empirical CTR curve fitting & intent classification
├── prioritizer.py   # "Clicks at Stake" ROI opportunity prioritization
├── inspector.py     # Quota-governed URL inspection triage engine
├── tracker.py       # SQLite persistence & 28-day change impact verifier
├── report.py        # Rich terminal formatting & Markdown report generator
├── mcp_server.py    # Model Context Protocol (MCP) server
└── cli.py           # Unified multi-command CLI entrypoint

🤝 Contributing

Contributions, feedback, and pull requests are very welcome!

  1. Fork the repository.

  2. Create your feature branch (git checkout -b feat/amazing-feature).

  3. Run the test suite: pytest -v.

  4. Commit your changes and open a PR.


📄 License

Distributed under the MIT License. See LICENSE for more information.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides AI agents with read-only access to Google Search Console data, including search analytics, index coverage, and sitemap status. It enables users to query clicks, impressions, and ranking performance or check URL indexing status through natural language.
      4
      133 npm
      9
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Transforms raw Google Search Console signals into actionable marketing insights, such as detecting cannibalization, segmenting search intent, and identifying citation opportunities, for any MCP-compliant AI agent.
      15
      1,320 PyPI
      40
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to access Google Search Console search performance and index health data, including clicks, impressions, rankings, URL inspection, and sitemap management.
      32 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to analyze Google Search Console SEO data through natural language, including search analytics, URL inspection, sitemap management, and property management.
      21
      MIT