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/handoffreturnslink,codeandpoll_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/pollreturnspending,approved,denied,expiredordone. Onapproved, open the returnedredirect_urlin the browser that started the connection.
Read-only tools
list_websites
List the websites you can access in DuckDive, with their connected data sources.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
search | string | No | "" | Optional text to match against website name or URL. |
limit | integer | No | 50 | Maximum rows to return (1-100). |
offset | integer | No | 0 |
get_website
Get one website's name, URL and connected data sources.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. |
get_sync_status
Show, per data source, whether the website's data is ready, importing or failing, and how recent it is.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. |
get_ga4_overview
Google Analytics 4 sessions and conversions per day, with totals and conversion rate.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
time_range | "last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months" | No | last30days |
get_ga4_channels
GA4 sessions and conversions broken down by channel group (medium) or traffic source.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
time_range | "last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months" | No | last30days | |
group_by | "medium" | "source" | No | medium |
get_ga4_landing_pages
Top GA4 landing pages by sessions, with conversions and conversion rate.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
time_range | "last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months" | No | last30days | |
limit | integer | No | 25 | Maximum rows to return (1-100). |
get_search_console_summary
Google Search Console clicks, impressions, CTR and average position over time.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
time_range | "last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months" | No | last30days |
get_search_console_keywords
Top Google search queries for the website by clicks.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
time_range | "last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months" | No | last30days | |
limit | integer | No | 25 | Maximum rows to return (1-100). |
get_search_console_pages
Top pages in Google search results for the website by clicks.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
time_range | "last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months" | No | last30days | |
limit | integer | No | 25 | Maximum rows to return (1-100). |
get_google_ads_summary
Google Ads spend, clicks, impressions, conversions and cost per conversion for the website's account.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
time_range | "last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months" | No | last30days |
get_lsa_summary
Google Local Services Ads leads, charged leads and spend for the website's account.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
time_range | "last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months" | No | last30days |
get_yext_summary
Yext listing status across publishers plus searches, views and actions over time.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
time_range | "last7days" | "last14days" | "last30days" | "last90days" | "last6months" | "last12months" | No | last30days |
get_yext_reviews
Review counts and average rating for the website's Yext location, by publisher and star rating.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. |
get_local_rankings
Local Falcon map rankings: average rank and top-3 share per tracked keyword.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
keyword | string | No | "" | Optional tracked keyword; when set, the latest ranking grid is included. |
search
Search your DuckDive websites by name or URL. Returns ids to use with fetch.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes |
fetch
Fetch a website returned by search: its URL and the status of each connected data source.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes |
get_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.
list_available_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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | No | null |
Action tools
refresh_website_data
Queue a re-import of recent data from Google and other sources. Admins only; once per website every 15 minutes.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
source | No | null | ||
days | integer | No | 7 | How many recent days to re-import (1-30). |
create_scheduled_report
Schedule a recurring DuckDive email report. It is always sent to your own account email. Admins only.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_ids | list of integer | Yes | ||
frequency | "daily" | "weekly" | "monthly" | Yes | ||
data_sources | "all" | "ga4" | "gsc" | "google_ads" | "lsa" | "yext" | "heatmaps" | No | all | |
time_range | "last7days" | "last10days" | "last30days" | "alltime" | No | last30days |
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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
url | string | Yes | The website address, e.g. https://example.com. | |
name | string | No | "" | Optional display name; defaults to the domain. |
client_id | No | null |
connect_website_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.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
website_id | integer | Yes | DuckDive website id from list_websites or search. | |
ga4_property_id | string | No | "" | GA4 property_id. |
search_console_site_url | string | No | "" | Search Console site_url. |
google_ads_account_id | string | No | "" | Google Ads customer_id. |
lsa_account_id | string | No | "" | Local Services Ads account_id. |
move_from_other_website | boolean | No | false | True only after the user agreed to move it from the website named in the error. |
replace_existing | boolean | No | false | True only after the user agreed to replace the source this website already uses. |