Documentation
Connect your marketing data to Claude, ChatGPT and other LLMs.
MCP Tools — Search Console
24 tools exposed on the https://gadspilot.com/mcp-gsc endpoint. Click a tool to see its parameters.
💡
You never need to call these tools manually — ask your question in plain English to Claude/ChatGPT/Cursor, the LLM picks the right tool, handles the parameters and summarizes the response. This doc just lists what's available.
📊 Reporting & Insights (16)
gsc_search_analytics
Read
Query GSC Search Analytics. Returns rows of (keys, clicks, impressions, ctr, position) aggregated over the date range with the requested dimensions. Supports query/page/country/device/date dimensions.
Parameters
site_url
*
|
string | The GSC property site_url (e.g. "https://example.com/" or "sc-domain:example.com"). |
start_date
*
|
string | YYYY-MM-DD. |
end_date
*
|
string | YYYY-MM-DD. |
dimensions
*
|
array | |
row_limit
|
integer | Default 100, max 25000. |
filters
|
array | Optional. Array of {dimension, operator, expression} objects. E.g. [{"dimension":"page","operator":"contains","expression":"/blog"}]. |
gsc_top_queries
Read
Shortcut for top search queries over a period (dimension=query). Returns the top N queries by clicks.
Parameters
site_url
*
|
string | |
start_date
*
|
string | |
end_date
*
|
string | |
row_limit
|
integer | |
page_contains
|
string | Optional. Filter to queries that landed on pages containing this substring. |
gsc_top_pages
Read
Shortcut for top pages by clicks (dimension=page) over a date range.
Parameters
site_url
*
|
string | |
start_date
*
|
string | |
end_date
*
|
string | |
row_limit
|
integer |
gsc_inspect_url
Read
URL Inspection API — check the indexing status, canonical URL, mobile usability, and rich results of a specific URL as Google sees it.
Parameters
site_url
*
|
string | |
page_url
*
|
string | The full URL of the page to inspect (must belong to the property). |
gsc_search_analytics_compare
Read
Compare GSC Search Analytics between two periods. Returns rows with {keys, current, prior, delta} for each dimension key (clicks/impressions absolute + relative, CTR in percentage points, position in rank points where decrease = better). Dropped queries (present in prior but not current) are included with dropped=true. Typical use: "compare last 28 days vs previous 28 days" or "this month vs same month last year".
Parameters
site_url
*
|
string | The GSC property site_url. |
start_date
*
|
string | Current period start (YYYY-MM-DD). |
end_date
*
|
string | Current period end (YYYY-MM-DD). |
compare_start_date
*
|
string | Prior period start (YYYY-MM-DD). |
compare_end_date
*
|
string | Prior period end (YYYY-MM-DD). |
dimensions
|
array | Default ["query"]. |
row_limit
|
integer | Rows per period, default 100. |
gsc_check_safe_browsing
Read
Check if a URL is flagged by Google Safe Browsing (malware, social engineering, unwanted software, potentially harmful app). Returns {safe: bool, verdict: "SAFE"|"UNSAFE", matches: [...]}. Requires a Google API key with Safe Browsing API enabled (Google Cloud Console → Credentials). Pass api_key as parameter, or configure google_api_key as a platform setting.
Parameters
url
*
|
string | The URL to check (full URL including scheme). |
api_key
|
string | Google API key (optional if google_api_key platform setting is configured). |
gsc_pagespeed
Read
Run Google PageSpeed Insights (Lighthouse) on a URL. Returns compact summary: performance/accessibility/best-practices/SEO scores, Core Web Vitals (LCP, CLS, INP, TBT, FCP, Speed Index), and top 5 opportunities with savings in ms. Use strategy="mobile" (default) or "desktop". api_key is optional (unauthenticated calls work but are rate-limited).
Parameters
url
*
|
string | The URL to analyze (full URL including scheme). |
strategy
|
string | Default "mobile". |
api_key
|
string | Google API key (optional, uses google_api_key platform setting as fallback). |
gsc_bulk_safe_browsing_sitemap
Read
Scan every URL of a sitemap (or sitemap index — recursive up to depth 3) against Google Safe Browsing v4 in batches of 500. Returns {sitemaps_visited, scan: {total, safe, unsafe, threats: [...]}}. Use this instead of calling gsc_check_safe_browsing per URL — 2000 URLs = 4 API calls vs 2000.
Parameters
sitemap_url
*
|
string | Full URL of sitemap.xml (index files supported). |
max_urls
|
integer | Safety cap, default 2000, hard max 10000. |
api_key
|
string | Google API key (optional, falls back to google_api_key platform setting). |
gsc_pagespeed_top_pages
Read
Pull the top N pages by clicks from GSC on the requested period, then run PageSpeed Insights on each for the requested strategies (mobile/desktop). Returns a compact leaderboard {pages: [{url, gsc: {clicks, impressions, ctr, position}, pagespeed: {mobile: {scores, lcp, cls, inp, top_opportunity}, desktop: {...}}}]}. top_n hard max 30 (PSI is slow: ~15-30s per URL per strategy).
Parameters
site_url
*
|
string | GSC property, e.g. "sc-domain:example.com" or "https://example.com/". |
start_date
*
|
string | YYYY-MM-DD (GSC has a 3-day delay — use dates ≥ 3 days ago). |
end_date
*
|
string | |
top_n
|
integer | Default 10, max 30. |
strategies
|
array | Default ["mobile"]. Both = ["mobile","desktop"] (doubles execution time). |
api_key
|
string | Google API key (optional, falls back to google_api_key platform setting). |
gsc_index_coverage_report
Read
Bulk index coverage audit — fetch a sitemap and inspect every URL via URL Inspection API. Returns aggregated counts (indexed / not_indexed / error) + per-URL verdict & coverage_state & canonical. Caps at 100 URLs per call (GSC quota ~2000/day). THE audit to run to find orphan/noindex/canonicalized pages.
Parameters
site_url
*
|
string | |
sitemap_url
*
|
string | Full sitemap URL (e.g. "https://example.com/sitemap.xml"). |
max_urls
|
integer | Max URLs to inspect (cap 100). Default 50. |
gsc_query_cannibalization
Read
Detect keyword cannibalization — queries where 2+ pages of the same site appear in Google results, competing with each other. Returns queries sorted by total_clicks impact + list of competing pages with position/clicks per page. Merge / canonicalize / differentiate intent = actions to take.
Parameters
site_url
*
|
string | |
start_date
*
|
string | YYYY-MM-DD |
end_date
*
|
string | YYYY-MM-DD |
min_pages_per_query
|
integer | Minimum pages competing to flag a query. Default 2. |
row_limit
|
integer | GSC row limit. Default 5000. |
gsc_crux_metrics
Read
Chrome UX Report — REAL-USER Core Web Vitals p75 for mobile+desktop, last 28 days rolling. LCP, INP, CLS, FCP, TTFB. This is the field data Google uses for ranking (vs PageSpeed lab estimates). Returns "not enough data" if the URL doesn't have enough real traffic.
Parameters
url
*
|
string | Absolute URL to query (page-level or origin-level). |
api_key
|
string | Optional. Same Google Cloud API key as PageSpeed (shared). |
gsc_content_decay
Read
Detect content decay — pages that lost ≥ threshold% of clicks between 2 periods. Sorted by absolute clicks lost (worst first). Use to trigger content refresh / rewrite. Params: two date ranges (current period vs prior period) + optional min_decline_pct + min_prior_clicks (filter noise).
Parameters
site_url
*
|
string | |
current_start
*
|
string | YYYY-MM-DD start of current period |
current_end
*
|
string | YYYY-MM-DD end of current period |
prior_start
*
|
string | YYYY-MM-DD start of prior period |
prior_end
*
|
string | YYYY-MM-DD end of prior period |
min_decline_pct
|
number | Threshold % (default 20) |
min_prior_clicks
|
integer | Ignore pages with < N clicks in prior period. Default 10. |
gsc_bulk_url_inspect
Read
Bulk inspect up to 100 individual URLs (vs `gsc_index_coverage_report` which reads a sitemap). Same signals: verdict, coverage_state, canonical, last_crawled per URL + aggregated counts.
Parameters
site_url
*
|
string | |
urls
*
|
array | Absolute URLs to inspect (cap 100). |
max_urls
|
integer | Cap. Default 50, hard max 100. |
gsc_ranking_diff
Read
Compare snapshotted rankings between 2 arbitrary dates (from gsc_ranking_snapshots table populated daily by cron). Returns winners (moved up), losers (moved down), new_entries (didn't exist before), disappeared. Historical position tracking beyond GSC's 16-month API limit. Params: site_url, from_date (YYYY-MM-DD), to_date, optional min_move (default 2 positions) + limit.
Parameters
site_url
*
|
string | |
from_date
*
|
string | YYYY-MM-DD older snapshot |
to_date
*
|
string | YYYY-MM-DD newer snapshot |
min_move
|
integer | Minimum position delta to include. Default 2. |
limit
|
integer | Max entries per bucket. Default 100. |
gsc_hreflang_audit
Read
Hreflang / international SEO audit — fetches HTML of each URL and checks: (a) reciprocity (each page A pointing to B must be pointed back), (b) x-default presence, (c) self-reference, (d) valid ISO codes. Caps at 20 URLs. Critical for multi-locale sites like /en/ /fr/ /es/…
Parameters
urls
*
|
array | List of absolute URLs to audit (all locale variants of the same page). |
max_urls
|
integer | Cap. Default 20. |
🏗 Structure & Listing (2)
gsc_list_properties
Read
List all Google Search Console properties authorized for this MCP token. Each property has site_url (either URL_PREFIX like "https://example.com/" or DOMAIN like "sc-domain:example.com"), permission_level, and label.
Parameters
gsc_list_sitemaps
Read
List all sitemaps submitted for a property, with status (lastSubmitted, lastDownloaded, isPending, isSitemapsIndex, errors, warnings).
Parameters
site_url
*
|
string |
✏️ Write actions (3)
All default to dry-run mode
gsc_submit_sitemap
Write · dry-run
Submit or resubmit a sitemap to GSC. WRITE operation. dry_run=true previews without calling the API.
Parameters
site_url
*
|
string | |
sitemap_url
*
|
string | The full URL of the sitemap (e.g. "https://example.com/sitemap.xml"). |
dry_run
|
boolean |
gsc_delete_sitemap
Write · dry-run
Remove a sitemap from GSC. WRITE operation. dry_run=true previews without calling the API.
Parameters
site_url
*
|
string | |
sitemap_url
*
|
string | |
dry_run
|
boolean |
gsc_request_indexing
Write · dry-run
Request Google to (re)index a URL via the Indexing API. WRITE. Officially restricted by Google to JobPosting/BroadcastEvent structured-data pages — for other pages the request may or may not be honored. Requires the "indexing" OAuth scope; if the property was connected before this scope existed, reconnect it at /gsc to grant the scope. dry_run=true previews without calling the API.
Parameters
site_url
*
|
string | |
page_url
*
|
string | Full absolute URL to submit (must belong to a domain covered by this GSC property). |
type
*
|
string | URL_UPDATED to (re)index, URL_DELETED to notify Google the URL is gone. |
dry_run
|
boolean |
🧠 Persistent memory (3)
Notes + change log shared across sessions
get_local_change_log
Read
Returns gadspilot's own write history for this account (every write tool call ever made via gadspilot, with parameters + result). Persistent across sessions. Use this BEFORE making changes to know what was already done previously. Different from get_change_history which only shows changes done via Google Ads UI/API.
Parameters
date_range
|
string | Default: last_30_days. |
tool_name
|
string | Optional filter — exact tool name (e.g. update_campaign_budget). |
campaign_id
|
string | Optional filter — only changes that touched this campaign. |
include_dry_run
|
boolean | Default: true. Set false to exclude previewed-only operations. |
get_notes
Read
Returns persistent notes attached to campaigns OR ad groups. Each note has a `level` field ("campaign" or "ad_group"). When recovering context for an ad group, ALWAYS pull both campaign-level (ad_group_id NULL) and ad-group-level notes — campaign context applies to all its ad groups.
Parameters
campaign_id
|
string | Optional — only notes for this campaign. |
ad_group_id
|
string | Optional — only notes for this specific ad group. |
scope
|
string | Default "all". Use "campaign_only" to get notes attached at campaign level (ad_group_id NULL), "ad_group_only" for notes attached to any ad group of the campaign. |
tags
|
array | Optional — only notes matching at least one of these tags. |
add_note
Read
Persists a free-text note. Attach at the MOST SPECIFIC level applicable: if the change/observation is about ONE ad group (bid, keywords inside, ads, RSA themes), pass ad_group_id. If it spans the whole campaign (budget, geo, bidding strategy, multi-AG insight), omit ad_group_id and only pass campaign_id. Use this to record WHY a change was made, hypotheses, or what to re-check later.
Parameters
campaign_id
*
|
string | |
ad_group_id
|
string | OPTIONAL but RECOMMENDED when the note is specific to one ad group. Omit only for campaign-wide notes. |
note
*
|
string | The note content. Be specific: include numbers, dates, hypotheses, re-check date. |
tags
|
array | Optional tags to organize notes (e.g. [\"experiment\", \"bid-test\", \"to-review\"]). |
General conventions
- READ tools: no risk, real-time read-only via Google Ads API / GSC API / Meta Marketing API
- WRITE tools: default
dry_run=true→ returns a JSON preview without modifying anything. You must explicitly passdry_run=falseto execute (and you can disable writes globally per account in gadspilot) - Memory tools: lightweight write to gadspilot DB only (notes/change log) — does not call Google/Meta APIs, no dry-run needed
- All monetary values are in micros on Google Ads (€1 = 1,000,000 micros). gadspilot automatically converts responses
- All writes are logged in /logs with params + result + dry-run flag
