Marketing and analytics tools
Search Console, Google Analytics, Google Ads and Microsoft Advertising tools in the developer API, with every argument.
Needs: Google Search Console, Google Analytics, Google Ads or Microsoft Advertising (Pro and Agency). 12 tools.
These tools appear in GET /v1/tools only when the API key's MCP server includes a connection of this kind. Call each one with POST /v1/tools/\<name>, sending its arguments as a JSON object. See Calling tools for the request and response format.
Marketing tools don't take an account from list_accounts. Call list_marketing_accounts for the sites, properties and ad accounts this key reaches, and pass their ids as accounts (leave it out for all). Sites or accounts you've hidden in Plugsight aren't listed and can't be read.
| Tool | What it does | Kind |
|---|---|---|
list_marketing_accounts |
List marketing accounts | Read |
list_marketing_fields |
List marketing data fields | Read |
get_marketing_data |
Get marketing data | Read |
marketing_deep_dive |
Marketing deep dive | Read |
search_console_inspect_url |
Inspect URL in Search Console | Read |
search_console_sitemaps |
List sitemaps | Read |
analytics_realtime |
Google Analytics 4 realtime | Read |
analytics_key_events |
GA4 key events | Read |
analytics_funnel |
GA4 funnel | Read |
analytics_metadata |
GA4 dimensions and metrics | Read |
google_ads_query |
Google Ads query (GAQL) | Read |
microsoft_ads_campaigns |
Microsoft Advertising campaigns | Read |
The example requests fill in only the required arguments, with placeholder values.
list_marketing_accounts
List marketing accounts · Read
Lists the marketing connections this MCP can use and everything they reach: Search Console sites, Google Analytics 4 properties, Google Ads customers (including accounts under a manager/MCC) and Microsoft Advertising (Bing Ads) accounts. Use the returned ids in the other marketing tools. Call this first.
| Argument | Type | Required | What it is |
|---|---|---|---|
service |
string | No | Only this service. One of: google_ads, microsoft_ads, search_console, analytics. |
search |
string | No | Only resources whose name or id contains this text |
refresh |
boolean | No | Re-discover now instead of using the 15-minute cache. Default false. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/list_marketing_accounts \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
list_marketing_fields
List marketing data fields · Read
Every field get_marketing_data accepts for a connector, as dimensions and metrics with descriptions. Derived metrics (ctr, cpc, cpa, roas, conversion_rate…) are recalculated after combining rows, so they stay correct across accounts.
| Argument | Type | Required | What it is |
|---|---|---|---|
connector |
string | Yes | google_ads, microsoft_ads (Microsoft Advertising / Bing Ads), search_console, analytics (GA4) One of: google_ads, microsoft_ads, search_console, analytics. |
search |
string | No | Only fields whose name or description contains this |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/list_marketing_fields \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"connector": "google_ads"}'
get_marketing_data
Get marketing data · Read
The main analysis tool. Pulls any combination of dimensions and metrics from Google Ads, Microsoft Advertising, Search Console or GA4, for one, several or all connected accounts at once, and returns a compact table with totals. Pick fields from list_marketing_fields. The right report is chosen automatically (e.g. search_term → search-term report, keyword → keyword report). Examples: converting keywords: fields [keyword, match_type, campaign, cost, conversions, cpa, conversion_value, roas] with filter conversions gt 0; wasted spend: [search_term, keyword, cost, clicks, conversions] with conversions eq 0 and cost gt 20; SEO: [query, page, clicks, impressions, ctr, position]. Rows from different accounts are combined unless account_name is a field. data_notes explain any data Google/Microsoft withhold.
| Argument | Type | Required | What it is |
|---|---|---|---|
connector |
string | Yes | google_ads, microsoft_ads (Microsoft Advertising / Bing Ads), search_console, analytics (GA4) One of: google_ads, microsoft_ads, search_console, analytics. |
fields |
array of string | Yes | Dimensions and metrics, in output column order |
accounts |
array of string | No | Account / customer / property ids or site URLs from list_marketing_accounts. Omit for all |
date_preset |
string | No | Used when date_from/date_to aren't given. Default last_30d. One of: today, yesterday, last_7d, last_14d, last_28d, last_30d, last_90d, last_180d, last_365d, this_month, last_month, this_year, last_year. |
date_from |
string | No | YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo") |
date_to |
string | No | YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo") |
filters |
array of object | No | All combine with AND. Text matching ignores case. Metric filters apply after combining rows. Default []. |
order_by |
array of object | No | Default: first metric, descending |
limit |
integer | No | Rows returned (after sorting) Default 500. |
max_rows_per_account |
integer | No | Rows fetched per account before combining. Default 100000. |
totals |
boolean | No | Add a totals row. Default true. |
options |
object | No | Advanced report options. Default {}. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/get_marketing_data \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"connector": "google_ads", "fields": []}'
marketing_deep_dive
Marketing deep dive · Read
Ready-made analyses that combine several queries and return findings plus tables:
- account_overview: every connected platform/account, this period vs previous (spend, conversions, CPA, ROAS, organic clicks, sessions, revenue)
- wasted_spend (google_ads/microsoft_ads): non-converting search terms and keywords, % of budget wasted, negative-keyword candidates
- scale_opportunities (ads): campaigns/keywords at or below average CPA that lose impression share to budget or rank
- search_term_winners (ads): converting search terms not yet added as keywords
- quality_score_audit (ads): spend by quality score and which component drags low scores down
- paid_vs_organic (ads + Search Console): paying where you rank top 3, paid winners with weak SEO, organic queries worth a paid test
- seo_opportunities (Search Console): striking-distance queries, low-CTR snippets, pages losing clicks
- period_comparison (any connector, needs fields): this period vs previous period or last year, biggest gains and drops Use get_marketing_data to drill into anything a deep dive surfaces.
| Argument | Type | Required | What it is |
|---|---|---|---|
report |
string | Yes | Which ready-made analysis to run. One of: account_overview, wasted_spend, scale_opportunities, search_term_winners, quality_score_audit, paid_vs_organic, seo_opportunities, period_comparison. |
connector |
string | No | Ads reports: google_ads (default) or microsoft_ads. period_comparison: any. One of: google_ads, microsoft_ads, search_console, analytics. |
accounts |
array of string | No | Account ids for the connector. Omit for all |
site_urls |
array of string | No | Search Console sites for paid_vs_organic / seo_opportunities. Omit for all |
date_preset |
string | No | Default last_30d. One of: last_7d, last_14d, last_28d, last_30d, last_90d, last_180d, last_365d, this_month, last_month, this_year, last_year. |
date_from |
string | No | YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo") |
date_to |
string | No | YYYY-MM-DD, or "today", "yesterday", "NdaysAgo" (e.g. "28daysAgo") |
compare |
string | No | Period to compare with. One of: previous_period, previous_year. Default "previous_period". |
fields |
array of string | No | period_comparison: dimensions + metrics, e.g. [campaign, cost, conversions, cpa] |
filters |
array of object | No | period_comparison only |
min_cost |
number | No | Spend threshold for wasted_spend lists. Default 10. |
min_conversions |
number | No | Conversion threshold for winners / scale reports. Default 1. |
min_impressions |
number | No | Impression threshold for SEO reports. Default 100. |
top |
integer | No | Rows per table. Default 25. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/marketing_deep_dive \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"report": "account_overview"}'
search_console_inspect_url
Inspect URL in Search Console · Read
Index status of one URL as Google sees it: coverage, last crawl, canonical, mobile usability, rich results.
| Argument | Type | Required | What it is |
|---|---|---|---|
site_url |
string | Yes | Site from list_marketing_accounts that contains the URL |
url |
string | Yes | Full URL to inspect |
language_code |
string | No | For translated issue messages, e.g. en-GB |
connection |
string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/search_console_inspect_url \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_url": "…", "url": "…"}'
search_console_sitemaps
List sitemaps · Read
Sitemaps submitted for a Search Console site, with submitted/indexed counts, errors and warnings.
| Argument | Type | Required | What it is |
|---|---|---|---|
site_url |
string | Yes | Search Console site from list_marketing_accounts (optional with one site) |
connection |
string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/search_console_sitemaps \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"site_url": "…"}'
analytics_realtime
Google Analytics 4 realtime · Read
Activity in the last 30 minutes, e.g. activeUsers by country, unifiedScreenName or eventName (GA4 API names).
| Argument | Type | Required | What it is |
|---|---|---|---|
property_id |
string | Yes | GA4 property id from list_marketing_accounts (optional with one property) |
metrics |
array of string | No | GA4 realtime metrics. Default ["activeUsers"]. |
dimensions |
array of string | No | GA4 realtime dimensions. Default []. |
limit |
integer | No | Most results to return. Default 50. |
connection |
string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/analytics_realtime \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"property_id": "…"}'
analytics_key_events
GA4 key events · Read
The events a GA4 property counts as key events (conversions), with how many happened and the key event rate in a period. Use it to answer 'what counts as a conversion here' and 'which conversions are happening'. For breakdowns by channel or page, use get_marketing_data with conversions.
| Argument | Type | Required | What it is |
|---|---|---|---|
property_id |
string | Yes | GA4 property id from list_marketing_accounts (optional with one property) |
start_date |
string | No | YYYY-MM-DD, "today", "yesterday" or "NdaysAgo". Default "28daysAgo". |
end_date |
string | No | YYYY-MM-DD, "today", "yesterday" or "NdaysAgo". Default "yesterday". |
connection |
string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/analytics_key_events \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"property_id": "…"}'
analytics_funnel
GA4 funnel · Read
Builds a funnel from 2–10 steps and shows how many users reach each step, the completion rate and where they drop off. Each step is an event (e.g. view_item, add_to_cart, begin_checkout, purchase) or a page (page view whose URL contains text). Closed funnels (default) count users who start at step 1; open funnels let users enter at any step. Optionally break down by a dimension such as deviceCategory or sessionDefaultChannelGroup.
| Argument | Type | Required | What it is |
|---|---|---|---|
property_id |
string | Yes | GA4 property id from list_marketing_accounts (optional with one property) |
steps |
array of object | Yes | Funnel steps, in order: each a name and an event |
open_funnel |
boolean | No | true: people can enter at any step. Default false. |
breakdown |
string | No | GA4 dimension, e.g. deviceCategory |
start_date |
string | No | YYYY-MM-DD, "today", "yesterday" or "NdaysAgo". Default "28daysAgo". |
end_date |
string | No | YYYY-MM-DD, "today", "yesterday" or "NdaysAgo". Default "yesterday". |
connection |
string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/analytics_funnel \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"property_id": "…", "steps": []}'
analytics_metadata
GA4 dimensions and metrics · Read
All dimensions and metrics available for a GA4 property, including its custom definitions. Any of these work in get_marketing_data.
| Argument | Type | Required | What it is |
|---|---|---|---|
property_id |
string | Yes | GA4 property id from list_marketing_accounts (optional with one property) |
search |
string | No | Only fields whose name or description contains this |
connection |
string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/analytics_metadata \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"property_id": "…"}'
google_ads_query
Google Ads query (GAQL) · Read
Runs any read-only Google Ads Query Language SELECT against one customer, for anything get_marketing_data doesn't cover. Rows come back flattened ("campaign.name", "metrics.clicks"). cost_micros ÷ 1,000,000 = account currency. Manager accounts can't report metrics; query their clients.
| Argument | Type | Required | What it is |
|---|---|---|---|
customer_id |
string | Yes | Customer id from list_marketing_accounts (dashes optional) |
query |
string | Yes | GAQL SELECT statement |
limit |
integer | No | Most results to return. Default 500. |
connection |
string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/google_ads_query \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"customer_id": "…", "query": "…"}'
microsoft_ads_campaigns
Microsoft Advertising campaigns · Read
Campaign settings in a Microsoft Advertising account: status, type, budget and bidding strategy.
| Argument | Type | Required | What it is |
|---|---|---|---|
account_id |
string | Yes | Account id from list_marketing_accounts (optional with one account) |
connection |
string | No | Connection id from list_marketing_accounts. Optional: a connection that reaches the resource is picked automatically. |
Example request:
curl -X POST https://app.plugsight.app/v1/tools/microsoft_ads_campaigns \
-H "Authorization: Bearer $PLUGSIGHT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"account_id": "…"}'