How to connect Supermetrics Marketing Analytics MCP with TypeScript

Query data from Google Ads, Facebook Ads, Google Analytics, LinkedIn Ads, TikTok Ads, Microsoft Ads, Shopify, HubSpot, and 200+ other platforms. Use data_source_discovery, accounts_discovery and field_discovery first. Returns rows when completed; else pass schedule_id to get_async_query_results. Team- and data-source-level context arrives with data_source_discovery/accounts_discovery, and a narrowed accounts_discovery (≤3 accounts) inlines an account's own context — apply what you already have. Only when you are querying a specific account whose context you have not seen, read it first with manage_business_context (action 'get', ds_id + account_id) for reporting guidelines — e.g. which campaigns to exclude, how to segment data, preferred metrics. If the user specifies reporting preferences during the conversation (e.g. "exclude brand campaigns", "always break out Advantage+ separately", "for this client we only look at last-click attribution"), ask whether to save these as context for future sessions using manage_business_context with action 'save'.

Retrieve results from a data_query using its schedule_id. Call immediately; the call waits, so it usually returns data first time. While pending, call again immediately; stop when status is 'completed' or failed. Map columns by requested_field_ids/canonical_field_ids, not the row-0 display names.

Discover data sources or get a source's configuration. Without ds_id: lists all sources with auth status; data-out-capable sources carry data_out: true (can receive activated audiences), others omit it. With ds_id: returns config (capabilities, report_types, settings, login link if needed). With filter: narrows the list; single match returns full config automatically.

Discover connected accounts for a data source. Only call if data_source_discovery config shows has_account_list=true. RETURNS: account_id, account_name, group_name (when present), tags (when present), and any saved business context for the account: shown as `context` when short enough to include, otherwise as `context_tags` naming what context exists — when a tag is relevant to the action you're taking, fetch that context with manage_business_context get (ds_id + account_id, filtered by tag).

Discover available fields (metrics and dimensions) for a data source. Only call if data_source_discovery config shows has_fields=true. Fields in a query must share a common report_type if the source uses report types.

Get current UTC date and time. Use before data_query with custom date ranges to resolve relative date references (e.g. "last month") into specific dates.

Instagram and Facebook (Meta) social media analytics and insights, using the same parameters and result format as data_query. Returns rows when completed; otherwise pass schedule_id to get_async_query_results. Metrics include engagement, engagement rate, reach, accounts reached, accounts engaged, followers, fans, follower growth, impressions, profile and page views, website and link clicks, top posts and best-performing content, content performance, stories, reels, video views, saves, likes, comments, shares, and audience demographics. Data sources (pass one as ds_id): - "IGI" — your connected Instagram business/creator account insights (media, reels, stories, top posts, follower demographics); - "IGPD2" — public data on any Instagram profile or hashtag (competitor benchmarking, business discovery, hashtag search); - "FB" — organic Facebook Page insights (page and post engagement, reach, fans/followers, impressions); - "FA" — Facebook & Instagram paid ad performance (Meta Ads); add the "publisher_platform" dimension to separate Facebook from Instagram placements (values include facebook and instagram; filter or segment on publisher_platform = instagram for Instagram-only ad metrics). Then use accounts_discovery to find the account IDs to pass in ds_accounts, and field_discovery to find the available field/metric IDs (and report types) for your chosen ds_id. To create or update Instagram (or Facebook) ad campaigns, use the manage_campaign tool. For any other platform (Google Ads, GA4, LinkedIn Ads, TikTok, and 170+ other data sources), use the data_query tool.

Manage your Supermetrics account: user and license info, team members and invites, data-source login links, subscription user assignment, and viewing or changing a data source prioritised (pinned) accounts with the cap and monthly change quota. Operations: get_info; invite_member; login_data_source (ds_id); add_user_to_subscription (license_id, user_ids); get_prioritised_accounts (ds_id); set_prioritised_accounts (ds_id, account_ids). Use get_info to find license_id and team member user_ids.

Send feedback, create a support ticket (only when the user authorizes it), or submit a sales enquiry. For a common problem, first call supermetrics_guide and try the relevant steps before opening a ticket. Only ticket if that does not resolve it or it needs staff action (refunds, cancelling a paid subscription (for a trial, use the cancel_trial guide), account deletion, trial extensions, non-self-serve plan changes, or a genuine bug); if you do, note which guide was tried and what still failed. When you create a support ticket, always set "category" to the option that matches the user's issue (authentication, billing, subscription, cancellation, data discrepancy, or query help). For product feature requests, you can also point users to the public wishlist at https://wishlist.supermetrics.com, where they can submit and vote on ideas. For standard purchases, direct users to buy online at https://supermetrics.com/pricing. Only submit a sales enquiry for special needs: many data sources, data source accounts, users, or other custom requirements. You can also check on existing support tickets: use type "ticket_status" (no ticket_id to list your tickets, or with a ticket_id to read its replies) and type "ticket_reply" to post a follow-up. Only your own tickets are accessible, and only post a reply when the user explicitly asks. Before creating a support ticket, first call type "ticket_status" (no ticket_id) to list the user's existing tickets and check whether an open one already covers the same issue. If it does, add to that ticket with type "ticket_reply" instead of creating a duplicate; only create a new ticket when none of the open tickets match.

Store and retrieve durable business context — guidelines, policies, and preferences a team wants applied consistently and shared with all members. Context can cover reporting conventions, analysis rules, brand and tone, data governance, naming, plans, or account-specific preferences. Stored at three scopes, each read independently (a `get` returns one scope's context, not a merge): - **Team** — applies everywhere (e.g. "report currency in EUR"). - **Data source** — a specific platform (e.g. "for Meta, break out Advantage+ separately"). - **Account** — a specific account (e.g. "this client reports last-click only"). **Actions:** - `get` — Retrieve context by scope, chosen by the ids (no cascade): no ids → team-level; `ds_id` → that data source's level; `ds_id`+`account_id` → that account's level. `tags` filters by tag — a record matches if it carries **any** of the tags you pass (OR); commas are just separators, so `tags: ["a,b"]` and `["a","b"]` both match records tagged a or b — handy for fetching several clients at once (e.g. one client tag per client, then `["acme,globex"]`). Omit `tags` to read all entries at the scope, and **`tags` with no ids searches across all scopes**, so a tag lookup isn't confined to one level. Returned grouped as `team`/`data_source`/`account` (empty omitted); a single-source data-source list is keyed `data_source:<ds_id>` (e.g. `data_source:AW`). To assemble everything applicable to an account, read the levels separately — or rely on the discovery tools, which surface applicable context automatically. - `save` — Create/update at a scope; needs `context_text` and `tags` (a tag can't contain a comma). Tags identify the entry within a scope, so a scope can hold several entries (one per tag set): `mode: "replace"` (default) overwrites the entry with those tags, `mode: "append"` concatenates to it, and a different tag set is saved as a separate entry rather than overwriting. - `delete` — Remove the single entry identified by scope (`ds_id`/`account_id`) **and** `tags` — it targets that one tag set, never the others at the scope. Omit `tags` to remove the untagged entry. Irreversible, so confirm first. **When to save:** when the user shares a plan, guidelines, or SOP; states a durable preference ("for this client, always…"); or corrects your approach — offer to save it so it applies in future sessions. Distill the key, reusable rules — do not store documents verbatim — and tag them (e.g. "data-analysis", "targeting", "naming-conventions", "brand-visuals", "brand-language"). Tags are how you retrieve an entry later — use category tags, or, to group context the scope can't (an agency client that spans several accounts and platforms), the client's name: a team-level entry tagged with a client name that maps the client to its accounts is a good pattern. Avoid tags that merely restate the scope (a data-source entry's own data source, an account's own id). **When to read:** prefer what the discovery tools already surface — `data_source_discovery` and `accounts_discovery` include team- and data-source-level context in their responses, and a narrowed `accounts_discovery` (≤3 accounts) inlines an account's own context. When a discovery response surfaces a scope only as a tag list (its context was too large to inline), read the tags relevant to the action you're taking with `get`. Also call `get` for a scope a discovery response did not cover — e.g. an account you are about to act on that was not in a discovery result — or to re-read after you `save`. A discovery response also states when the team has no saved context yet, so don't call `get` merely to check whether any exists. Apply context when analysing data and making changes.

Share live dashboards in Supermetrics Studio — self-contained pages that re-query the user's data on each view, so a shared link always shows current numbers. Before uploading, show a STATIC inline preview (data hard-coded, no smQuery), then confirm before uploading the LIVE smQuery version. smQuery and window.fetch work only inside Studio, so a preview using them renders empty in the chat — the inline preview must hard-code the data you already fetched, and the upload must fetch via smQuery (see the 'code' param), never the hard-coded preview. ALWAYS offer this upload after building a dashboard — it is how users discover Studio; do not just show the preview and stop. Skip the confirmation only when the user EXPLICITLY asked to publish (e.g. "put this in Studio and give me a link"). Actions: - 'upload': Upload a new dashboard or replace an existing one. Requires title, code, allowed_tools, allowed_accounts; description is optional. The code format (HTML or JSX) is detected automatically. - 'get': Retrieve a dashboard's source code and metadata by ID. Use this to load current code before editing. - 'edit': Apply targeted anchor-based patches to dashboard code. Call 'get' first to see the current code, then send patches. - 'changelog': View version history with change descriptions. - 'list': List the dashboards the user owns or has been shared with (metadata only, no code), newest first. Optional 'filter' narrows by id, title, description, or tag (case-insensitive substring). Optional 'limit' (default 20, max 500) and 'offset' paginate; the response carries 'total' (compare it with the number of dashboards returned to know whether more remain). Edit patch types (pick the smallest that fits): - region replace (PREFER for changing a section's logic/content): {"from": "// #region charts", "to": "// #endregion charts", "replace": "// #region charts\n<new code>\n// #endregion charts"} — replaces the WHOLE region from 'from' to 'to', anchor lines INCLUDED. Write the COMPLETE new block in 'replace' and reproduce the 'from' and 'to' marker lines inside it (normally unchanged) so they survive; omitting a marker deletes it. Restating an anchor does NOT duplicate it. 'from' must be unique; 'to' is the first match after it. - find/replace (small unique swap): {"find": "old text", "replace": "new text"} - after/insert (a NEW element): {"after": "anchor text", "insert": "new content"} - before/insert: {"before": "anchor text", "insert": "new content"} Modifiers (find/replace only): "nth": N (target Nth occurrence), "all": true (replace all). Patches are applied sequentially and atomically. Patchable code: When uploading, wrap each section in PAIRED region markers so edits can target them, and declare each variable/function inside the region that uses it: - HTML: <!-- #region header -->…<!-- #endregion header --> - CSS: /* #region kpi-cards */…/* #endregion kpi-cards */ - JS: // #region chart-init … // #endregion chart-init - Tag key elements with data-sm attributes: data-sm="kpi-spend", data-sm="filter-date" Each anchor must be unique in the code. Best practices: - Add a loading indicator (spinner or skeleton) while data is being fetched. - When it makes sense, add selectors (dropdowns, date pickers, toggles) that let viewers change query parameters such as date range, account, or metric. - Date controls: offer a genuinely flexible date range, not just a few fixed presets. smQuery's date_range_type accepts today, yesterday, this_month(_inc), last_month, this_year_inc, last_year(_inc), and the last_x_days / last_x_weeks_sun_sat / last_x_weeks_mon_sun / last_x_months / last_x_years families — substitute a number for x (e.g. last_90_days, last_3_months) and append _inc to include the current period. There is NO native quarter or year-to-date preset: deliver 'this/last quarter', 'year to date', and any viewer-picked custom range via date_range_type="custom" with start_date/end_date (YYYY-MM-DD) computed in the dashboard's own JS (derive the boundaries from new Date()). Prefer including a fully custom start/end picker alongside the presets. - Period comparison: when comparison is wanted, add ONE dashboard-wide comparison control and feed the SAME compare params into EVERY widget's smQuery — time-series charts too, not only scorecards. compare_type="prev_range" (previous period), "prev_year" (same period last year), "prev_year_weekday", or "custom" (with compare_start_date/compare_end_date, YYYY-MM-DD); compare_show="perc_change" (default), "abs_change", or "value". For a year-over-year time-series overlay, either use compare_type or issue a second smQuery for the prior period and plot it as an additional series. - Give each chart/table/KPI its own stable smQuery key (see the 'code' param) so rapidly changing a selector can't show stale data from a previous selection. - If an 'upload' response includes `code_warnings`, the board will render empty/wrong data or never refresh — fix the issue it names (a static board with no smQuery calls, or column mapping via requested_field_ids) and re-upload before sharing the board.

Explain what Supermetrics can do, what's new, or how to fix a common problem. Use mode="tour" (the default) for what the user can do; mode="whats_new" for recent changes. Not for looking up data sources, accounts or fields. Call tour/whats_new at most once per conversation. TROUBLESHOOTING: when the user reports a common problem, fetch the matching guide and walk them through it before offering a support ticket. Connecting / access: connect_data_source (sign-in / "no accounts found"), google_connectors (GA4/Search Console/YouTube/etc. access), meta_instagram (Facebook/Instagram setup), microsoft_connectors (Microsoft Ads/Bing Webmaster), linkedin_connectors (Ads vs Company Pages), tiktok_connectors (Ads vs Organic), x_twitter_connectors (X Ads vs X Organic), amazon_connectors (Ads/DSP/Seller/Vendor), data_warehouse (BigQuery/Snowflake), reconnect (expired connection). Licensing and accounts: license_and_trials (LICENSE_NOT_FOUND / trial expired), cancel_trial (cancel a trial / "will I be charged?"), data_source_on_plan (LICENSE_DATA_SOURCE_NOT_AVAILABLE), destination_on_plan (AI Chats destination missing), prioritized_accounts ("not a prioritised account"), manage_users_and_accounts (adding users/accounts and making a new account usable). Data and queries: no_data (empty results), data_discrepancies (numbers don't match the platform), ga4_data (GA4 sampling/thresholding/partial data), query_errors (date/field/account errors), quotas_and_limits (quota exceeded). Campaigns: write_access. Each returns steps the user can follow without Supermetrics staff.

Free marketing utilities: no Supermetrics subscription or connected data source needed. **Actions:** - utm_build: tag each of the urls with source/medium/campaign/term/content, correctly encoded (macros like {campaignid} kept), validated against your team's conventions. - utm_parse: audit the urls against your team's conventions and GA4 channel rules. - pagespeed_check: PageSpeed Insights for up to 10 urls (run in parallel; 30s-2min): scores, lab and field vitals, top fixes; detail="full" for every finding. Returns within ~45s; if checks are still running it returns status="running" and a job_id: poll with {"action":"pagespeed_check","job_id":...} about every 30s. Results are cached for 24h (cached=true, checked_at); pass refresh=true only after the page has changed. - link_check: follow up to 50 urls through redirects; do UTM and click-id params (gclid, fbclid...) reach the landing page, and at which hop are they lost. Also broken pages, loops, tagging mistakes. - web_vitals_trend: ~6 months of real-user LCP/INP/CLS/FCP/TTFB for up to 50 sites (bare domain) or pages. - safety_check: up to 50 urls and every host they redirect through: Web Risk malware/phishing flags, invalid or expiring certificates, domains expiring soon or registered in the last 30 days. - link_preview: how up to 50 urls render when shared on LinkedIn, Facebook, X and Slack; flags missing or small og:image, missing description, truncated titles. - email_dns: SPF, DKIM, DMARC, MX and BIMI for up to 50 domains (urls may be domains, emails or URLs). - char_limits: exact lengths of up to 200 texts against Google Ads, Meta, LinkedIn and X limits (counted as each platform counts). Use it whenever copy must fit a limit; do not count characters yourself. Google asset fields (path, long_headline, business_name, callout, sitelink_text, sitelink_description) are checked only when named in field. **Results:** every result has input (as sent), url, status (ok|warning|critical|unknown) and findings[] of {code, severity, message, suggestion?, ...extras}; unknown results carry error {code, message} (e.g. quota_exhausted, daily_limit, no_data, url_throttled). Each batch has a summary of counts. **UTM conventions** come from business context (tags='utm-conventions'). A JSON object is enforced; every key is optional; lists are exact, case-sensitive matches: {"approved_sources":[...],"approved_mediums":[...],"blocklist":{"utm_campaign":["test"]}, "regex":{"utm_campaign":"\d{4}"},"max_length":{"utm_campaign":60},"casing":"lowercase"|"as_is", "separator":"-"|"_","require_all_core":true} When utm_source is a known ad network (google, bing, facebook/instagram, tiktok, linkedin, snapchat, pinterest), utm_build returns network {medium, campaign_macro, id_macro, click_id} and both actions flag macros written in another network's syntax, which that network would leave unfilled. utm results report conventions_source: team (JSON enforced), team_free_text (returned as team_conventions for you to apply) or defaults (lowercase, hyphens).

Create or update a campaign (AW/FA/TIK/LIA/AC/CGPTA/SCM). Provide campaign_id to update an existing campaign; omit it to create a new one (budget_amount required when creating). On update only provided fields change. Also creates/updates ad groups/ads — see ad_groups (operations inferred from id presence). AW PMax: set ad_groups[].id to update asset groups. AW/AC keywords: ad_groups[].add_keywords/remove_keywords append/remove POSITIVE keywords; targeting REPLACES (send full set). Partial success possible: check write_status and failures if present, otherwise notes; don't retry blindly. Creative: use asset_url (public https:// URL), asset_id, upload_ref (from creative_picker), or object_story_id (existing post). Use campaign_and_resource_get for full details after writing.

Get campaigns or related resources. Unless you already fetched it this session, call manage_business_context with action 'get' (passing ds_id and account_id) to fetch applicable guidelines — e.g. which campaigns to focus on, how to evaluate performance, reporting preferences — and reuse that result for the rest of the session. resource_type options (pass options in params): - campaigns (default): list or get single campaign. optional params: {status, campaign_id, campaign_detail_level} Ad groups/ads are INSIDE campaigns — use campaign_id + campaign_detail_level, not a separate resource_type. - health_check: 30-day snapshot. params: {campaign_id}. Custom dates/breakdowns: use data_query instead - forecast: estimate performance at spend levels (AW/FA). params: {bids, targeting, optimization_goal} - assets: account creative library (images/videos). Use id as asset_id in creatives - pages (FA Pages), posts (FA promotable posts, params: {page_id}). - keyword_ideas/keyword_volumes (AW/AC). params: {keywords, url, language, location} - targeting_search: search targeting catalog. params: {query, type} - reach_estimate: audience size. params: {targeting} - audiences, recommendations, history: params: {campaign_id} where applicable - experiments: campaign experiments / A/B tests with status, type and date range (AW) - negative_keyword_lists: shared negative keyword lists with keywords and campaigns using them (AW) - conversion_types: conversion actions and any pixels (definitions, not per-campaign counts). data_query for metrics - approval_status: outcome of a change sent for approval. params: {approval_ref}

Open the creative picker to browse, upload, AI-generate, or import ad creatives with visual preview. Works with both image and video creatives. Use it whenever the user wants to add an image or video. Pass asset_url or asset_prompt in params to auto-start; if the user already has an asset URL or ID, pass it directly to manage_campaign instead.