Skip to main content
Glama
GSC Opportunity MCP

GSC Opportunity MCP

by caomicc

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 .env

Authentication

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.json

Either 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. Default 5 is 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 token

  • list_sites — properties the credentials can read

  • get_top_opportunities — the headline: all three signals, ranked by estimated revenue

  • get_striking_distance_keywords — queries at position 4-15 with gap to page 1

  • get_page_performance — one URL: totals plus the queries driving it

  • analyze_content_decay — pages losing clicks versus the prior window

  • find_cannibalization — queries split across multiple pages

  • get_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 -q

Tests 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 tools
analyze_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

    B3.2/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides 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
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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