| name | google-search-console |
| description | Pull real Google Search Console data (queries, impressions, clicks, CTR, average position, indexing status) for the configured site via `bun run dispatch google-search-console`. Use this instead of guessing what users search for, whenever you need SEO or search-traffic evidence. |
| disable-model-invocation | true |
Google Search Console (Kevin's analytics plugin)
Real search traffic data for the configured site. The GSC_SITE_URL env var names the Search Console property; the authenticated OAuth2 client lives under app/.config/ and is shared with other google- plugins* (currently google-page-speed) — one consent flow covers all.
Commands
Invoke as bun run dispatch google-search-console <cmd> [args...]. Output is always JSON on stdout — pipe through jq for filtering.
The command surface is a closed set: query, inspect, sites, auth. There is no overview, summary, totals, compare, or wow command — do not invent one. Rollups and period-over-period deltas are computed from query output with jq (see "Totals & WoW" under Common patterns).
query <start> <end> [--dim=query,page] [--page=<url>]
Search-analytics query. Dates in YYYY-MM-DD. Default dimension is query (top search terms). Returns rows sorted by clicks.
--dim= picks the row shape; --page=<url> scopes the query to a single page (applies a dimension=page, operator=equals filter). The two are independent — you can run --dim=query --page=<url> to list the top queries for that one URL.
Flags accept both --flag=value and --flag value forms.
mcp__plugin_agent-kevin_kevin__gsc_query 2026-04-13 2026-04-19
mcp__plugin_agent-kevin_kevin__gsc_query 2026-03-20 2026-04-19 --dim=page
mcp__plugin_agent-kevin_kevin__gsc_query 2026-04-13 2026-04-19 --dim=query,page
mcp__plugin_agent-kevin_kevin__gsc_query 2026-04-13 2026-04-19 --page=https://example.com/topic-keyword-a/
mcp__plugin_agent-kevin_kevin__gsc_query 2026-04-13 2026-04-19 | jq '.[:10] | .[] | {keys:.keys[0], clicks, impressions, ctr, position}'
Row shape:
{ "keys": ["<query string>"], "clicks": 12, "impressions": 340, "ctr": 0.035, "position": 8.2 }
inspect <url>
URL inspection — indexing status, last crawl time, mobile usability, rich-results. Use to diagnose why a specific page isn't ranking or getting traffic.
mcp__plugin_agent-kevin_kevin__gsc_inspect https://example.com/topic-keyword-e
sites
List verified properties accessible with the current credentials. Useful when query fails with a permission error — confirm the GSC_SITE_URL string matches exactly (including sc-domain: prefix for domain properties vs. full URL for URL-prefix properties).
mcp__plugin_agent-kevin_kevin__gsc_sites | jq '.[] | .siteUrl'
Common patterns
Totals & week-over-week (site-wide rollup for the current period vs prior period):
mcp__plugin_agent-kevin_kevin__gsc_query 2026-03-23 2026-04-19 --dim=page \
| jq '{clicks: (map(.clicks) | add),
impressions: (map(.impressions) | add),
ctr: ((map(.clicks) | add) / (map(.impressions) | add)),
avg_position: ((map(.position * .impressions) | add) / (map(.impressions) | add))}'
mcp__plugin_agent-kevin_kevin__gsc_query 2026-02-23 2026-03-22 --dim=page \
| jq '{clicks: (map(.clicks) | add), impressions: (map(.impressions) | add)}'
Avg position must be impression-weighted (not a flat mean), or pages with few impressions will distort the number.
Find underperforming pages (high impressions, low CTR):
mcp__plugin_agent-kevin_kevin__gsc_query 2026-04-01 2026-04-19 --dim=page \
| jq 'map(select(.impressions > 100 and .ctr < 0.02)) | sort_by(-.impressions)'
SEO opportunity scan (pages ranking #11–20 with traffic):
mcp__plugin_agent-kevin_kevin__gsc_query 2026-03-20 2026-04-19 --dim=query,page \
| jq 'map(select(.position > 10 and .position < 20 and .impressions > 50)) | sort_by(-.impressions)'
Diagnose a specific page:
mcp__plugin_agent-kevin_kevin__gsc_inspect https://example.com/topic-keyword-c
When to use vs not
- ✅ "What queries drove traffic last week?" →
query
- ✅ "Is this URL indexed?" →
inspect
- ✅ "Why is this page losing rank?" →
query with --dim=page for traffic trend, then inspect for technical issues
- ❌ "What should I write about?" — GSC tells you what you're already ranking for. Use Perplexity for broader topic research.
- ❌ Real-time traffic or analytics (sessions, bounce rate) — that's GA4 territory, not Search Console.
Setup note
If commands fail with "Tokens not minted" — the one-time OAuth dance hasn't been run yet:
mcp__plugin_agent-kevin_kevin__google_auth
This opens a browser, captures Google's consent, and persists the refresh token to .kevin/secrets/google/google-tokens.json (alongside the OAuth client JSON, in the deny-gated secrets dir) — the same token is used by every google- plugin*, so you only run auth once, not once per plugin. You handle this once per install; Kevin should not normally need to run auth.