MCP-Tools – Referenz

Plain-English map of every WinningHunter MCP tool.

• Die meisten Tools sind schreibgeschützt; Marke, track_storeund save_ad write; get_ad_transcript can generate persisted transcripts
• Erfolgreich Tools/Anruf uses 1 API credit. A call that returns an error payload (ungültiges Argument, not_found, auth_required, …) is refunded and reports credit_charged: false

Schnellübersicht#

search_tiktok_products
search_tiktok_shops
search_tiktok_creators
search_tiktok_videos
browse_tiktok_categories
list_tiktok_category_top
autocomplete_tiktok
count_tiktok_entities
get_tiktok_product
get_tiktok_shop
get_tiktok_creator
get_tiktok_video
get_tiktok_trending_products
search_tiktok_ads
get_tiktok_ad
search_pinterest_ads
get_pinterest_ad
search_google_ads
get_google_advertiser
get_store_details
get_store_top_ads
search_facebook_ads
find_winning_products
creative_inspiration_pack
brief_competitor
scan_ad
get_ad_transcript
save_ad
list_saved_ad_boards
daily_radar
track_brand
analyze_tracked_brand
list_tracked_brands
track_store
list_shopify_store_filter_options
search_shopify_stores
search_shops
find_similar_shops
find_similar_stores_by_image
search_exploding_topics
get_exploding_topic_detail
autocomplete_exploding_topics
check_credits

43 tools total. Anzahl der TikTok-Entitäten mirrors explore count endpoints (no row payload).

Response size#

Facebook-Anzeigen suchen / Gewinnerprodukte finden echo applied filters under mcp_filters (small). Full catalogs (zulässige Nischen, allowed_technologies, filter_reference, …) are opt-in: pass include_filter_reference=true. Without that flag, discover codes via an invalid filter value (returns allowed_values / zulässige Nischen without running the search).

search_tiktok_ads, search_pinterest_adsund search_google_ads keep responses under the MCP client tool-result limit (~25k tokens) in three ways:

• Per-day chart series (*_history, *_timeseries — adspend_history, Rangverlauf, like_count_history, …) are dropped. The names appear in omitted_series_fields.
• Fields that carry a byte-identical duplicate value are folded to one canonical name. The response lists field_aliases, e.g. {"poster": "image", "text": "description"} — read the canonical field instead.
• If the rows still exceed the budget, the lowest-ranked ads are dropped and the response sets truncated: true with a truncated_reason. Lower Grenze or narrow the filters to get complete pages.

Ad search filters are validated#

The three ad-platform search tools reject unknown values instead of silently ignoring them. An invalid sort_by, Nischen, formatoder Bewertung Ergebnisse error: invalid_argument with the allowed list (allowed_sort_by, zulässige Nischen, …) and does not consume a credit. Every successful response echoes applied_filters so you can confirm what actually reached the query.

Niche taxonomies are per-platform#

Meta niche codes are not shared with the other platforms.

• TikTok has its own 15 keys: Schönheit, bags, car, romanticgifts, clothing, watches, jewelry, womenclothing, menclothing, toys, child, home, pet, gadgets, outdoor. Raw TikTok label_######## industry codes also work. Passing Meta codes returns ungültiges Argument with the valid keys.
• Pinterest und Google have no niche/category filter. Use Stichwort, domainoder promoter_name/advertiser_name.

Metric coverage by ad platform#

Not every metric exists on every platform. Sorting or filtering on an absent metric gives you noise, so pick a field the platform actually populates:

Two date fields are easy to confuse on Pinterest: Erstellt am is when WinningHunter indexed the ad (nearly always today), while begonnen is the ad's launch date. Beginn / bis filter begonnen.

Saved ads and boards#

save_ad is board-backed for every platform: facebook, facebook_post, pinterest, google und tiktok. Omit board_id to land on the default "All Saved Ads" board, or call list_saved_ad_boards first and pass a specific board_id. Saving the same ad to the same board twice is a no-op and comes back as already_saved: true.

TikTok used to be the exception — saves went to a separate per-user list and board_id was ignored. That is no longer the case. TikTok saves now go to boards like everything else and are additionally mirrored into the legacy per-user list, which is what keeps the filled heart and the "saved only" toggle on the /tiktok-ads grid working. TikTok ads saved before this change stay visible under "All Saved Ads" but are not attached to a board until they are saved again.

Store technology codes#

Technologien on the TikTok and Pinterest ad tools takes two-letter codes, not product names: SH Shopify, WC WooCommerce, WP WordPress, PP PayPal, KL Klaviyo, GO Google Analytics, CO Cookiebot, TP Trustpilot, SL ShopLazza, SI ShopLine, MG Magento.

Wie man über die Werkzeuge nachdenkt#

1) Dinge finden#

Verwende zuerst diese:

• TikTok-Produkte suchen
• TikTok-Shops suchen
• TikTok-Creators suchen
• TikTok-Videos suchen
• Facebook-Anzeigen suchen
• Gewinnerprodukte finden
• Kreativ-Inspirationspaket
• kurze_Wettbewerber
• scan_ad
• Shopify-Shops suchen
• Geschäfte suchen
• Ähnliche Geschäfte finden
• Ähnliche Geschäfte anhand eines Bildes finden
• Suche nach aktuellen Themen

2) Details anzeigen#

Verwende eine ID aus den Suchergebnissen:

• get_tiktok_product
• get_tiktok_shop
• get_tiktok_creator
• get_tiktok_video
• get_exploding_topic_detail

3) Helfer#

• TikTok-Kategorien durchsuchen (Kategoriebäume und Ansichten)
• Liste der beliebtesten TikTok-Kategorien (Top-Artikel in einer Kategorie)
• autocomplete_tiktok (Vorschläge bei der Eingabe)
• autocomplete_explodierende_Themen (Themenvorschläge)
• get_tiktok_trending_products ( trending TikTok Shop)
• daily_radar (tracked-brand growth summary; set include_creative_signals=true for per-brand creative tabs — slower)
• Marke (Eine Meta-Seite zum Brand Tracker hinzufügen)
• analyze_tracked_brand (Einzelmarken-Tiefgang)
• track_store (Einen Shopify-Shop/eine Domain zum Store Tracker hinzufügen)
• list_shopify_store_filter_options (gültige Filterwerte für den Store Explorer, einschließlich dynamischer Themen/Apps/Taxonomie)
• save_ad (save a creative to Saved Ads)
• list_saved_ad_boards (board ids and folders for save_ad; covers every platform, TikTok included)
• get_ad_transcript (fetch or generate an ad transcript)
• Abspann (programmatic API pool — same shape as REST GET /api/v1/credits: used / Grenze / remaining / addon_remaining / total_remaining)

Die häufigsten Argumente#

Die meisten Suchmaschinen verwenden diese:

• Stichwort
• Land
• Seite
• Größe
• sort_by
• Sortierreihenfolge

Für Meta-Werbetools, Seite ist in MCP 1-basiert (1 = first page), even though the dashboard backend uses 0-based indexing internally. Deep pagination requires the opaque scrollen cursor from the previous response (mcp_pagination.scroll_next) — incrementing Seite alone does not advance the result set (especially with sort_by=lastseen).

Sortierreihenfolge ist asc oder Beschreibung (Standard Beschreibung) bei jedem Werkzeug, das dies unterstützt.

Die meisten Detailwerkzeuge verwenden:

• id
• Scheibe (welchen Teil du möchtest)

Zulässig sort_by pro Werkzeug#

Geben Sie eine beliebige Zeichenfolge aus der folgenden Tabelle ein. Gängige Aliase werden automatisch normalisiert (Groß-/Kleinschreibung wird nicht berücksichtigt). In allen anderen Fällen wird die Standardsortierung verwendet, und die Antwort enthält einen mcp_sorting Abschnitt, in dem beschrieben wird, was angewendet wurde.

Meta-Anzeigenbibliothek#

Aliasnamen: erstellt / Erstellt am / Datum / vor kurzem / neueste / aktuell → Datum gefunden; most_recent / mostrecent / ad_started / ad_creation → mostrecent; Anfang der letzten Anzeige → zuletzt gesehen; erste_Anzeige_gestartet / älteste / frühest → Datum gefunden (aufsteigend); aktive Anzeigen → pageactiveads; monatliche Besuche → monatliche Besuche. Für markeninterne Anzeigenrang („Top-Anzeige von [Marke]“), verwende Spitzenplatz oder Aliase Rang, Rangliste, Anzeigenrang, top_ad, am besten bewertet, best_ad, adrank, topad, …; Phrasen mit Leerzeichen wie Spitzenplatz / Anzeige oben auf ... normieren Spitzenplatz. Sortierreihenfolge wird ignoriert für Spitzenplatz (immer in aufsteigender Reihenfolge).

Suchbegriff (Gültigkeitsbereich für Stichwort (zu Meta-Tools): Alle (Standard), Ziel-URL, Seitenname, Anzeigentext, Produktname. Das ist nicht ein Nischen-/Kategorienfeld; Aliase wie Ziel-URL, Seitenname, ad_text, Produkt werden ebenfalls normalisiert. Wenn ein Agent versehentlich einen Nischen-/Kategoriebegriff als Suchbegriff ohne Stichwort / Nische (zum Beispiel Suchbegriff: „Mode“), stellt das MCP-Tool es als das passende Nische (CG) anstatt die Schemavalidierung nicht zu bestehen.

Für die vertikale Suche bzw. die Suche nach Kategorien bei Meta verwenden Sie Nische oder Nischen anstelle einer reinen Stichwortfilterung. Behandeln Sie Benutzerbegriffe wie „Kategorie“, „Nische“, „Branche“, „Markt“ oder „Produktkategorie“ als Anfrage für diesen Meta-Nischenfilter. Das MCP-Eingabeschema stellt die Nischencodes des Dashboards als Aufzählung bereit, sodass eine Mode-Abfrage wie folgt gesendet werden sollte: Nische=CG (Mode & Bekleidung). Nützliche Verfeinerungen bei Modeanzeigen sind WC = Damenbekleidung, MC = Herrenbekleidung, FW = Schuhe, BG = Taschen, JY = Schmuck, WT = Uhrenund SG = Sonnenbrillen. Die Laufzeitumgebung akzeptiert auch Dashboard-Namen wie Mode & Bekleidung; ungültige Werte führen zu zulässige Nischen anstatt weitergeleitet zu werden.

Rangwachstumsfilter wird zudem anhand der Dashboard-Optionen überprüft: durch Kommas getrennt steigend, stabil, abnehmend.

Andere Filter des Meta-Dashboards werden als MCP-Argumente bereitgestellt und vor dem Aufruf validiert /api/fb-ads: Länder / Länder ausschließen, Technologie / Technologien, Sprache / Sprachen / Sprachen ausschließen, Apps / exclude_apps, Thema / Themen, Skalierung, Medientyp, Seitentyp, Bewertung, geringe Impressionen, Bereichsfilter (min_* / max_* for duplicates, active ads, FB page likes, ad spend, reach, monthly visits, products on store, price, copy length, video length, days running), active-ads % growth (min_active_ads_growth / max_active_ads_growth + active_ads_growth_period — human percent, periods 1w | 1m | 3m nur; dashboard 14d/2m and EU reach % growth are omitted from MCP), and date ranges (ad_created_*, zuletzt_gesehen_*, product_created_*, page_created_*). Themennamen müssen genau den Werten der Dashboard-Themen entsprechen; Apps akzeptieren Dashboard-App-IDs oder App-Namen. Für Datumsbereiche sind beide Angaben erforderlich *_von und *_zu in JJJJ-MM-TT.

scan_ad (ad detail / angles)#

Use when the user is viewing one ad and wants hook, angle, landing page, days running, or a scaling read.

Do not pass context.ad.landing_url, brand domains, or product pages — those are storefront URLs, not ad ids. Use web_fetch separately only if you need on-page product copy from the landing URL.

Returns: hook, angle, landing_page, days_running, verdict (likely_scaling | early_or_testing | insufficient_data), plus full ad row.

TikTok Shop#

Alle Suchfunktionen im TikTok Shop sind standardmäßig auf sort_by=Umsatz. Die zulässigen Werte entsprechen den sortierbaren Spalten des Dashboards.

Pagination: TikTok explore tools use keyset cursors: omit danach on the first call; pass meta.next_cursor (also echoed as mcp_pagination.after_next) as danach on the next call with the same filters/sort. When danach is set, the backend ignores Seite. Prefer danach for deep downloads; Seite remains fine for shallow offset paging. Stop when next_cursor / after_next is null. (HTTP explore uses the same danach cursor on /api/v1/tiktok-shop/{entity}/explore.)

Für Liste der beliebtesten TikTok-Kategorien, get_tiktok_product (Urheber / Videos Scheiben), get_tiktok_shop (Produkte / Videos / Urheber Scheiben), get_tiktok_creator (Geschäfte / Produkte / Videos Scheiben) und get_tiktok_video (ähnlich Scheibe), die Sortierfeld arg verwendet die oben angegebene Zulassungsliste der entsprechenden Entität.

Aliase werden in allen TikTok Shop-Tools automatisch normalisiert: verkaufte Einheiten / Einheiten / Umsatz / verkauft → Anzahl der verkauften Artikel; gmv → Umsatz; gmv_30d / Umsatz_30d → Umsatz_30_Tage; Wachstum / Umsatzwachstum / gmv_Wachstumsrate → Umsatzwachstumsrate; Umsatzwachstum → Umsatzwachstumsrate; Preis / Durchschnittspreis → Durchschnittspreis; Bewertung → Shop-Bewertung; Bewertungen → Anzahl der Produktbewertungen; Anzahl der Follower → Follower; Aufrufe → Aufrufe_in_den_letzten_30_Tagen; Likes → Likes in den letzten 30 Tagen; roas → geschätzter_ROAS; Dauer → Videolänge; Datum / veröffentlicht → Veröffentlichungsdatum.

Shopify – Shops entdecken#

track_store(store_url) Fügt dem Store Tracker einen Shop/eine Domain hinzu. Es verwendet dieselben Validierungsregeln, Plan-Limits, Shop-Auflösung und Bestseller-Scrape-Warteschlange wie das Dashboard.

Aliasnamen: Umsatz / Monatsumsatz / Umsatz_30d / 30d_Umsatz → 30d_rev_geschätzter_Maximalwert; Jahresumsatz / Jahresumsatz → Umsatz_1J; Tagesumsatz / Umsatz_1d → 1d_rev_geschätzter_Maximalwert; Verkehr / Besuche / Besucher / monatliche Besucherzahlen → monatliche Besuche; Durchschnittlicher Bestellwert / durchschnittlicher Bestellwert / Bestellwert → Durchschnittlicher Warenkorbwert; Verkehrswachstum_1M → Besucherwachstum_in_Prozent_M1; Verkehrswachstum_3M → Besucherwachstum_in_Prozent_M3; Umsatzveränderung / Umsatzdynamik / Umsatzentwicklung des Geschäfts in den letzten 30 Tagen → Besucherwachstum_in_Prozent_M1 (gleiche Zuordnung wie in der Live-Tabelle „Explore Shops“, als die alte Sortierung nach Umsatzdifferenz abgeschafft wurde).

Shopify-Shops suchen / Geschäfte suchen Filter (alle optional, sofern nicht anders angegeben). Die Namen entsprechen den Namen der MCP-Argumente:

Verwendung list_shopify_store_filter_options bevor nach dynamischen Werten gefiltert wird (Shopify-Themes, Store-Apps, Produkt-Taxonomie_Ebene_1/2/3). Seine Abschnitt Das Argument akzeptiert alle, statisch, Themen, Apps, Produkt-Taxonomie_Ebene_1, Produkt-Taxonomie_L2, Produkt-Taxonomie_L3; weiter Abfrage um dynamische Optionslisten zu durchsuchen.

Leitfaden für das Intent-Modell: „Nischenläden“ → Kategorie oder Nische = einer der Bereiche von Explore Shops. Für Mode/Kleidung/Bekleidung verwende Kleidung. Vermeiden Sie Stichwort-nur Nischenanfragen. „Top / umsatzstärkste“ → sort_by=Umsatz_1j, sort_order=desc. „Neu in den letzten N Monaten“ → aus_dem_Shop_erstellt / store_created_to einschließlich JJJJ-MM-TT (beides erforderlich).

Gleichheit mit POST-https://app.winninghunter.com/api/shops/explore: MCP verwendet dieselben serverseitigen POST-Schlüssel (Suche, Kategorie, Sortierschlüssel, Sortierrichtung, Seite, Seitengröße, includeWlads, …). Argumentzuordnung: Stichwort→Suche, sort_by→Sortierschlüssel, Größe→Seitengröße. Standard include_wlads=false → includeWlads=0 (entspricht der Abfrage der Dashboard-Tabelle, bei der die Vorschau von WLADs übersprungen wird).

Ähnliche Geschäfte anhand eines Bildes finden dauert Bild-URL (erforderlich) sowie die dieselben Filter wie oben, mit Ausnahme von Stichwort (Die Ähnlichkeitssuche ersetzt die Textsuche).

Hinweis: Die TikTok-MCP-Tools nutzen ebenfalls ein Land Argument – da ist es: Marktplatz/Länderkontext, nicht derselbe Bereich wie bei Shopify-Händlern Land.

Marken-Tracker#

track_brand(page_id?, url?) fügt dem Brand Tracker eine Facebook-/Meta-Seite hinzu. Geben Sie entweder eine Seiten-ID oder eine URL der Facebook-Anzeigenbibliothek, die Folgendes enthält alle_Seiten-ID; es nutzt dieselbe Plan-Obergrenze und dieselbe globale Tracking-Warteschlange wie das Dashboard.

Aliasnamen: vor kurzem / hinzugefügt / neueste / aktuell / Datum → Datum der Aufnahme; alphabetisch / alpha / A–Z → Name; neu / neue Anzeigen → neue Anzeigen; trending / Schwung → Wachstum.

Heiße Themen#

Aliase für Sortieren: Umfang → absolutes Volumen; exponentiell → Exponent; vor kurzem / neueste / aktuell → Datum der Aufnahme; trending → Wachstum. Kategorie akzeptiert Dashboard-Slugs (z. B. Mode, Schönheit, Hautpflege, Fitness, Technologie, ai, …) oder Standard für alle Kategorien.

mcp_sorting Antwortblock#

Jedes Such- oder Listentool, das sort_by (oder sortieren/Sortieren) fügt eine mcp_sorting Objekt in der Antwort-Nutzlast:

{
  "mcp_sorting": {
    "requested_sort_by": "revenue_30d",
    "applied_sort_by": "revenue_30_days",
    "applied_sort_order": "desc",
    "allowed_sort_by": ["revenue", "name", "revenue_30_days", "..."],
    "normalized_from": "revenue_30d"
  }
}

Wenn Sie einen unbekannten Sortierschlüssel übergeben, mcp_sorting.warning es heißt, es sei auf die Standardeinstellung zurückgefallen – das Tool gibt keinen Fehler aus.

Schnittwerte für Detailwerkzeuge#

Verwende eine dieser Optionen Scheibe Werte:

• get_tiktok_product: Detail, Geschichte, Kennzahlen, Urheber, Videos
• get_tiktok_shop: Detail, Geschichte, Kennzahlen, Produkte, Videos, Urheber, Strategie
• get_tiktok_creator: Detail, Geschichte, Kennzahlen, Geschäfte, Produkte, Videos
• get_tiktok_video: Detail, Geschichte, Kennzahlen, Produkte, ähnlich

Zwei häufige Fehler#

1. Trending

   • get_tiktok_trending_products ist die Produktdynamik von TikTok Shop
   • „Exploding Topics“ ist ein eigenständiges Projekt (Suche nach aktuellen Themen + get_exploding_topic_detail)

2. Schreibvorgänge

   • MCP unterstützt Marke, track_store, save_ad, and Meta ad transcript generation via get_ad_transcript
   • Favorites, presets, TikTok transcripts, and other writes must use REST API

Block für KI-Anweisungen kopieren#

Fügen Sie dies in die Anweisungen für den Makler ein:

Use WinningHunter MCP at https://app.winninghunter.com/mcp.
Auth can be either OAuth bearer token (connector flow) or X-API-Key (header-capable clients).
Most MCP tools are read-only. `track_brand`, `track_store`, and `save_ad` write. `get_ad_transcript` can generate persisted transcripts.
Successful tools/call costs 1 API credit.
If user asks for other writes (favorites/presets/TikTok transcripts), use REST /api/v1/tiktok-shop/* instead.
When unsure about exact schema, call tools/list first.

Benötigen Sie die vollständigen technischen Details?#

Die vollständige Filter-Semantik und das Verhalten der Endpunkte finden Sie hier:

• TikTok Shop-Filter
• Meta-Anzeigenbibliothek
• Marken
• Shopify-Shop-Explorer
• Trends