Docs

MCP tool reference

The DuckDive MCP server gives AI agents read access to your marketing data, and lets admins run a few actions. This is every tool and its parameters.

Connect

The MCP server URL is https://api.duckdive.ai/mcp. It uses OAuth 2.0: when you add it to your AI app, a DuckDive page opens and you sign in (continue with Google). The app receives a DuckDive access token, never your password. This address is for AI apps, not browsers.

Step-by-step setup for each app is in Connect your AI. Guide for AI agents: https://analytics.duckdive.ai/agents.md. The same tool list as JSON for machines: https://api.duckdive.ai/mcp/tools.

Agents with their own browser

Google sign-in does not work in an agent's own browser or sandbox. Instead, the agent gets a link and a code for the user to open in their own browser, then polls until the user approves. Both calls use the request= value from the authorize page URL as request_token.

  • POST https://api.duckdive.ai/api/v1/mcp-oauth/handoff returns link, code and poll_url. Give the user the link and code.
  • GET https://api.duckdive.ai/api/v1/mcp-oauth/handoff/{code} says which app is asking (no sign-in).
  • POST https://api.duckdive.ai/api/v1/mcp-oauth/handoff/poll returns pending, approved, denied, expired or done. On approved, open the returned redirect_url in the browser that started the connection.

Read-only tools

Available to every connected account.

list_websites List websites

List the websites you can access in DuckDive, with their connected data sources.

ParameterTypeRequiredDefaultDescription
searchstringNo""Optional text to match against website name or URL.
limitintegerNo50Maximum rows to return (1-100).
offsetintegerNo0

get_website Get website

Get one website's name, URL and connected data sources.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.

get_sync_status Data sync status

Show, per data source, whether the website's data is ready, importing or failing, and how recent it is.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.

get_ga4_overview GA4 overview

Google Analytics 4 sessions and conversions per day, with totals and conversion rate.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
time_range"last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months"Nolast30days

get_ga4_channels GA4 channels

GA4 sessions and conversions broken down by channel group (medium) or traffic source.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
time_range"last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months"Nolast30days
group_by"medium" | "source"Nomedium

get_ga4_landing_pages GA4 landing pages

Top GA4 landing pages by sessions, with conversions and conversion rate.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
time_range"last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months"Nolast30days
limitintegerNo25Maximum rows to return (1-100).

get_search_console_summary Search Console summary

Google Search Console clicks, impressions, CTR and average position over time.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
time_range"last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months"Nolast30days

get_search_console_keywords Search Console keywords

Top Google search queries for the website by clicks.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
time_range"last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months"Nolast30days
limitintegerNo25Maximum rows to return (1-100).

get_search_console_pages Search Console pages

Top pages in Google search results for the website by clicks.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
time_range"last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months"Nolast30days
limitintegerNo25Maximum rows to return (1-100).

get_google_ads_summary Google Ads summary

Google Ads spend, clicks, impressions, conversions and cost per conversion for the website's account.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
time_range"last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months"Nolast30days

get_lsa_summary Local Services Ads summary

Google Local Services Ads leads, charged leads and spend for the website's account.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
time_range"last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months"Nolast30days

get_yext_summary Yext summary

Yext listing status across publishers plus searches, views and actions over time.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
time_range"last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months"Nolast30days

get_yext_reviews Yext reviews

Review counts and average rating for the website's Yext location, by publisher and star rating.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.

get_local_rankings Local rankings

Local Falcon map rankings: average rank and top-3 share per tracked keyword.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
keywordstringNo""Optional tracked keyword; when set, the latest ranking grid is included.

Search your DuckDive websites by name or URL. Returns ids to use with fetch.

ParameterTypeRequiredDefaultDescription
querystringYes

fetch Fetch

Fetch a website returned by search: its URL and the status of each connected data source.

ParameterTypeRequiredDefaultDescription
idstringYes

get_setup_status Setup status

Start here when the user is new, list_websites returns nothing, or the user asks to set up DuckDive. Returns the account (role, whether it can set things up, whether this connection may make changes), its clients, its websites with each data source's import status, whether Google is connected, suggested_websites (sites their Google account can see, when they have none yet), and next_step {code, message} saying exactly what to do next: add_website, connect_google, choose_sources, importing, ready or ask_admin. links holds pages to give the user (links.dashboard shows their data); links.connect_google, needed only when Google is not connected, must be opened by the user in their own browser. Never ask for passwords or Google credentials.

No parameters.

list_available_sources List available data sources

List the Google Analytics 4 properties, Search Console sites, Google Ads accounts and Local Services Ads accounts the user's connected Google logins can reach, to pick what connect_website_sources should link. Pass website_id to mark items matching that website's domain as suggested (listed first) and get ready_to_link: the one clear match per source that no other website uses, to link without asking. Ask the user only about the rest. Items already used by a website show linked_website_id and linked_website_name. Empty lists usually mean Google is not connected yet: give the user links.connect_google from get_setup_status.

ParameterTypeRequiredDefaultDescription
website_idNonull

Action tools

Admin accounts only.

refresh_website_data Refresh website data

Queue a re-import of recent data from Google and other sources. Admins only; once per website every 15 minutes.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
sourceNonull
daysintegerNo7How many recent days to re-import (1-30).

create_scheduled_report Create scheduled report

Schedule a recurring DuckDive email report. It is always sent to your own account email. Admins only.

ParameterTypeRequiredDefaultDescription
website_idslist of integerYes
frequency"daily" | "weekly" | "monthly"Yes
data_sources"all" | "ga4" | "gsc" | "google_ads" | "lsa" | "yext" | "heatmaps"Noall
time_range"last7days" | "last10days" | "last30days" | "alltime"Nolast30days

add_website Add website

Add a website to DuckDive so its marketing data can be imported. Use it when get_setup_status says add_website, with the address the user gives you. If the account has several clients the call fails and lists them: ask the user which one, then call again with client_id. Returns website_id and next_step. Nothing is imported until connect_website_sources links its data sources. Admins only.

ParameterTypeRequiredDefaultDescription
urlstringYesThe website address, e.g. https://example.com.
namestringNo""Optional display name; defaults to the domain.
client_idNonull

connect_website_sources Connect website data sources

Link a website to the GA4 property, Search Console site, Google Ads account and/or Local Services Ads account from list_available_sources (its ready_to_link, or what the user picked) and start importing their history. A GA4 property or Search Console site belongs to one website at a time. If it is already linked to another website the call fails and names it: ask the user, and only if they agree call again with move_from_other_website=true. If the website already uses a different one, the call fails and names it: ask the user, and only if they agree call again with replace_existing=true. Returns the website's import status; follow progress with get_sync_status. Admins only.

ParameterTypeRequiredDefaultDescription
website_idintegerYesDuckDive website id from list_websites or search.
ga4_property_idstringNo""GA4 property_id.
search_console_site_urlstringNo""Search Console site_url.
google_ads_account_idstringNo""Google Ads customer_id.
lsa_account_idstringNo""Local Services Ads account_id.
move_from_other_websitebooleanNofalseTrue only after the user agreed to move it from the website named in the error.
replace_existingbooleanNofalseTrue only after the user agreed to replace the source this website already uses.