GSC Opportunity MCP
Reads Google Search Console data using a read-only scope to rank SEO opportunities by estimated revenue. Provides tools for listing sites, finding striking-distance keywords, analyzing content decay, detecting cannibalization, and reviewing page performance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GSC Opportunity MCP show me my top search opportunities ranked by estimated revenue"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GSC Opportunity MCP
An MCP server that ranks Google Search Console opportunities by estimated revenue, not by clicks.
Most SEO tooling tells you what has the most traffic. This tells you what is worth fixing first: it scores every opportunity as projected incremental clicks x your revenue per 1000 clicks, and returns one ranked list you can work top to bottom.
Read-only. Scope is
webmasters.readonly. It cannot change your site or your property.Local. Runs on your machine against your own credentials. Nothing is sent anywhere but Google.
Transparent. The money figures are arithmetic you can audit, not a black-box score.
Headless-safe. Works in cron and agents; no interactive re-auth on token expiry.
What it gives you
Striking distance — queries ranking 4-15, i.e. page two and the bottom of page one. These are the cheapest wins on any site.
Content decay — pages that lost clicks versus the previous window, with the delta.
Cannibalization — queries where two or more of your pages compete and split authority.
Revenue ranking across all three — one list, sorted by dollars, not by category.
Related MCP server: Google Search Console MCP Server
Install
Requires Python 3.10+.
git clone https://github.com/<you>/gsc-opportunity-mcp.git
cd gsc-opportunity-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
cp .env.example .env # then edit .envAuthentication
The server uses Google Application Default Credentials. Two supported paths:
(a) User credentials (easiest locally)
gcloud auth application-default login \
--scopes https://www.googleapis.com/auth/webmasters.readonly(b) Service account (best for servers and cron)
Create a service account in a Google Cloud project with the Search Console API enabled, download the JSON key, then:
export GOOGLE_APPLICATION_CREDENTIALS=/absolute/path/to/key.jsonEither way, the credentials must have access to the property. User credentials inherit
your own access. For a service account you must add its email address
(something@project.iam.gserviceaccount.com) as a user on the Search Console property
itself — Settings -> Users and permissions -> Add user. Read permission is enough.
Configure
Edit .env:
CREATOR_SEO_SITE=sc-domain:example.com
CREATOR_SEO_SITE_RPM=5
CREATOR_SEO_AFFILIATE_CATEGORIES={}Use the domain property form (sc-domain:example.com) where possible: it covers
subdomains and both http/https.
About the numbers
Every dollar figure is an estimate used for ranking, and says so. Two inputs:
CREATOR_SEO_SITE_RPM— your display-ad revenue per 1000 pageviews. Default5is a placeholder. Set it to your real RPM and the ranking becomes meaningful.CREATOR_SEO_AFFILIATE_CATEGORIES— a JSON map of query/page substring to extra dollars per 1000 clicks.{"smart ring": 40}means queries containing "smart ring" score $40/1k higher. This is how commercial-intent pages float to the top.
Projected clicks assume a row can reach a 10% CTR (target_ctr), which is optimistic for
low-intent queries. It is a consistent yardstick for ordering work, not a revenue forecast.
If you use Raptive, set RAPTIVE_CLIENT_ID / RAPTIVE_CLIENT_SECRET
and the server uses real per-page RPM instead of the flat estimate. Without those
credentials it silently falls back to CREATOR_SEO_SITE_RPM — no Raptive account required.
Wire it into an MCP client
{
"mcpServers": {
"gsc-opportunity": {
"command": "/absolute/path/to/.venv/bin/gsc-opportunity-mcp",
"env": { "CREATOR_SEO_SITE": "sc-domain:example.com" }
}
}
}Tools
health_check— auth and config status; never hangs on an expired tokenlist_sites— properties the credentials can readget_top_opportunities— the headline: all three signals, ranked by estimated revenueget_striking_distance_keywords— queries at position 4-15 with gap to page 1get_page_performance— one URL: totals plus the queries driving itanalyze_content_decay— pages losing clicks versus the prior windowfind_cannibalization— queries split across multiple pagesget_raptive_revenue— real Raptive revenue, pageviews and blended RPM (optional)get_raptive_page_performance— per-page Raptive RPM and earnings (optional)
Development
.venv/bin/pip install pytest
.venv/bin/pytest -qTests run without network access or credentials.
Prior art
The revenue-weighted ranking idea is lifted from Yoshyaes/creator-seo-mcp, which requires
a separate OAuth client and a credentials.json that breaks on token expiry in headless
runs. This rebuilds the idea on plain ADC with a read-only scope.
License
MIT.
Available Tools
9 toolsanalyze_content_decayC
Pages losing clicks month-over-month (current window vs prior window).
Inputs: days, site, limit. Returns: result
find_cannibalizationC
Queries where two+ pages compete — authority is being split.
Inputs: days, site, limit, min_impressions. Returns: result
get_page_performanceC
Full GSC picture for one URL: totals + the queries driving it.
Inputs: url, days, site. Returns: object
get_raptive_page_performanceB
Per-page Raptive RPM + earnings for the window (highest revenue first).
Inputs: days, limit, site_id. Returns: result
get_raptive_revenueB
Real Raptive revenue for the window: total $, pageviews, and blended RPM.
Requires RAPTIVE_CLIENT_ID/SECRET in .env; raises a clear error otherwise.
Inputs: days, site_id. Returns: object
get_striking_distance_keywordsB
Queries ranking ~4-15 (page-2-to-top-3) — the most actionable growth band.
Each row reports the ranking page and the gap to page 1 (position - 3).
Inputs: days, site, limit. Returns: result
get_top_opportunitiesA
The headline: combine striking-distance, decay, and cannibalization into one ranked action list. Revenue-weighted with REAL per-page Raptive RPM when Raptive creds are configured in .env, else the flat CREATOR_SEO_SITE_RPM.
Inputs: days, site, limit. Returns: result
health_checkB
Auth + config status. Never hangs on expired tokens (headless-safe).
Inputs: no named parameters. Returns: object
list_sitesA
List Search Console properties the credentials can read.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools target a clearly distinct analytical question (decay, cannibalization, striking-distance, revenue). The main overlap is get_page_performance (GSC metrics for one URL) vs get_raptive_page_performance (Raptive RPM for pages), which are distinguishable only by the 'raptive' prefix, and get_top_opportunities partially aggregates the three analysis tools, so an agent may sometimes pick the detailed tool when the summary was wanted.
Strong snake_case convention with clear verb prefixes (get_/list_/analyze_/find_). health_check deviates from the verb_noun pattern, and find_cannibalization uses a concept rather than an object, but overall the pattern is predictable and readable.
Nine tools cover a narrow, well-defined SEO-analysis surface with each tool earning its place. No filler or near-duplicate tools beyond the intentional GSC-vs-Raptive split.
The surface covers the core lifecycle: auth check, property listing, per-page GSC detail, three distinct opportunity analyses, a combined ranking, and Raptive revenue (total and per-page). Minor gaps exist, such as no explicit date-range/window parameter tool and no query-level search outside the striking-distance band, but agents can work around these via the provided endpoints.
Maintenance
Related MCP Connectors
Google Search Console for AI assistants: traffic, rankings, indexing and page checks. Read-only.
Daily Google rankings for the keywords you choose, from your own Search Console data.
Query your Google Search Console, GA4 and Bing Webmaster data across every site you run.
Turn Search Console data into SEO actions, content, publishing, indexing, and AI insights.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides comprehensive access to Google Search Console data with enhanced analytics capabilities, supporting up to 25,000 rows of performance data, advanced filtering with regex patterns, and automatic detection of SEO optimization opportunities.MIT
- -licenseNot gradedqualityNot gradedmaintenanceProvides comprehensive access to Google Search Console data with enhanced analytics capabilities, supporting up to 25,000 rows of performance data, advanced filtering with regex patterns, and automatic quick wins detection for SEO optimization opportunities.2-
- AlicenseNot gradedqualityDmaintenanceEnables querying Google Search Console data including rankings, clicks, and impressions for websites. Provides tools for analyzing search performance, top queries, page metrics, and ranking changes.MIT
- FlicenseNot gradedqualityDmaintenanceEnables querying Google Search Console data via natural language, providing tools for site traffic analysis, page changes, and optimization opportunities.-