Skip to main content
Glama
README.md
# Google Search Console Agent Pro (GSC Pro)

<div align="center">

[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/alirazawebservice-rgb/google-search-console-agent-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/alirazawebservice-rgb/google-search-console-agent-pro/actions)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/alirazawebservice-rgb/google-search-console-agent-pro/pulls)

**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](#-1-minute-quickstart) • [Why GSC Pro (Comparison)](#-why-gsc-pro-the-advanced-difference) • [Terminal Preview](#-terminal-preview) • [CLI Commands](#-cli-commands) • [AI Agent Integration](#-ai-agent-integration-mcp) • [Architecture](#-architecture)

</div>

---

## 🚀 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.**

---

## 🌟 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: <br>$$\Delta\text{Clicks} = \text{Impressions} \times (\text{Target CTR} - \text{Observed CTR})$$<br> 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

```text
┌──────────────────────────────────── 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`:

```bash
# 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:

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

### 3. Run Your First Audit
```bash
# 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:
```bash
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:
```bash
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:
```bash
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:
```bash
# 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:
```bash
# 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
```bash
claude mcp add gsc-pro -- gsc-pro mcp
```

### Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "gsc-pro": {
      "command": "gsc-pro",
      "args": ["mcp"]
    }
  }
}
```

### Google Antigravity (`~/.gemini/settings.json`)
```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](LICENSE) for more information.