gsc-pro
README.md
# Google Search Console Agent Pro (GSC Pro)
<div align="center">
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/alirazawebservice-rgb/google-search-console-agent-pro/actions)
[](https://modelcontextprotocol.io/)
[](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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues