Documentation
Connect your marketing data to Claude, ChatGPT and other LLMs.
MCP Tools — Search Console
14 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 (7)
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). |
🏗 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 (2)
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 |
🧠 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