MCP tools reference (simple)

This is the plain-English version of the MCP tools list.

• MCP URL: https://app.winninghunter.com/mcp
• Full setup guide: Connect MCP
• All tools are read-only
• Successful outils/appel uses 1 API credit

Quick list (all 30 tools)#

search_tiktok_products
search_tiktok_shops
search_tiktok_creators
search_tiktok_videos
count_tiktok_entities
browse_tiktok_categories
list_tiktok_category_top
autocomplete_tiktok
get_tiktok_product
get_tiktok_shop
get_tiktok_creator
get_tiktok_video
get_tiktok_trending_products
search_facebook_ads
find_winning_products
creative_inspiration_pack
brief_competitor
scan_ad
daily_radar
analyze_tracked_brand
list_tracked_brands
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

How to think about the tools#

1) Find things#

Use these first:

• rechercher_des_produits_sur_TikTok
• rechercher_sur_TikTok_Shops
• rechercher_des_créateurs_sur_TikTok
• rechercher_des_vidéos_sur_TikTok
• search_facebook_ads
• find_winning_products
• creative_inspiration_pack
• brief_competitor
• scan_ad
• search_shopify_stores
• search_shops
• find_similar_shops
• find_similar_stores_by_image
• search_exploding_topics

2) Open details#

Use an ID from search results:

• récupérer_produit_tiktok
• get_tiktok_shop
• get_tiktok_creator
• récupérer_vidéo_TikTok
• get_exploding_topic_detail

3) Helpers#

• nombre_d'entités_TikTok (counts by entity)
• Parcourir les catégories TikTok (category tree and views)
• liste_catégorie_top_TikTok (top items in one category)
• suggestion automatique_TikTok (typeahead suggestions)
• autocomplete_exploding_topics (topic suggestions)
• get_tiktok_trending_products (TikTok Shop trending)
• daily_radar (tracked-brand changes)
• analyze_tracked_brand (single-brand deep dive)
• list_shopify_store_filter_options (valid Store Explorer filter values, including dynamic themes/apps/taxonomy)
• générique (remaining API credits)

Most common arguments#

Most search tools use these:

• mot-clé
• pays
• page
• taille
• sort_by
• sort_order

For Meta ad tools, page is 1-based in MCP (1 = first page), even though the dashboard backend uses 0-based indexing internally.

sort_order is asc ou desc (par défaut desc) on every tool that accepts it.

Most detail tools use:

• id
• slice (which part you want)

Autorisé sort_by per tool#

Pass any string from the table below. Common aliases are normalized automatically (case-insensitive). Anything else falls back to the default sort and the response includes a mcp_sorting block describing what was applied.

Meta ad library#

Alias : created / created_at / date / recent / newest / latest → datefound; last_ad_started → lastseen; first_ad_started / oldest / earliest → datefound (ascending); active_ads → pageactiveads; monthly_visits → monthlyvisits. For within-brand ad_rank (“top ad from [brand]”), use toprank or aliases rank, ranking, ad_rank, top_ad, best_ranked, best_ad, adrank, topad, …; spaced phrases like top rank / top ad normalize to toprank. sort_order is ignored for toprank (always ascending rank).

searchkeyword (field scope for mot-clé on Meta tools): Tous (default), landingurl, pagename, adtext, productname. This is pas a niche/category field; aliases like landing_url, page_name, ad_text, produit are normalized too. If an agent mistakenly sends a niche/category term as searchkeyword with no mot-clé / niche (for example searchkeyword: "Fashion"), the MCP tool recovers it as the matching niche (CG) instead of failing schema validation.

For Meta vertical/category searches, use niche ou niches instead of keyword-only filtering. Treat user wording like “category”, “niche”, “vertical”, “market”, or “product category” as a request for this Meta niche filter. The MCP input schema exposes the dashboard niche codes as an enum, so a fashion query should be sent as niche=CG (Mode et habillement). Useful fashion-ad refinements are WC = Women's Clothing, MC = Vêtements pour hommes, FW = Chaussures, BG = Sacs, JY = Bijoux, WT = Montres, et SG = Sunglasses. The runtime also accepts dashboard names like Mode et habillement; invalid values return allowed_niches instead of being passed through.

rank_growth_filter is also validated against the dashboard options: comma-separated rising, stable, declining.

Other Meta dashboard filters are exposed as MCP args and validated before calling /api/fb-ads: countries / exclude_countries, technology / technologies, language / languages / exclude_languages, apps / exclude_apps, theme / themes, scaling, media_type, page_type, ad_score, low_impressions, range filters (min_* / max_* for duplicates, active ads, ad spend, reach, monthly visits, products on store, price, copy length, video length, days running), and date ranges (ad_created_*, last_seen_*, product_created_*, page_created_*). Theme names must be exact dashboard Themes values; apps accept dashboard app ids or app names. Date ranges require both *_from et *_to en YYYY-MM-DD.

TikTok Shop#

All TikTok Shop search tools default to sort_by=revenue. Allowed values match the dashboard's sortable columns.

Pour liste_catégorie_top_TikTok, récupérer_produit_tiktok (créateurs / vidéos slices), get_tiktok_shop (produits / vidéos / créateurs slices), get_tiktok_creator (magasins / produits / vidéos slices), and récupérer_vidéo_TikTok (similar slice), the sort_field arg uses the matching entity's allow-list above.

Aliases auto-normalized across TikTok Shop tools: units_sold / units / sales / sold → sold_count; gmv → chiffre d'affaires; gmv_30d / revenue_30d → revenue_30_days; growth / revenue_growth / gmv_growth_rate → revenue_growth_rate; sales_growth → sales_growth_rate; price / avg_price → avg_unit_price; rating → shop_rating; revues → product_review_cnt; followers_count → followers; views → views_30_days; likes → likes_30_days; roas → estimated_roas; duration → video_duration; date / published → date_de_publication.

Shopify Explore Shops#

Alias : chiffre d'affaires / monthly_revenue / revenue_30d / 30d_revenue → 30d_rev_estimated_max; annual_revenue / yearly_revenue → revenue_1y; daily_revenue / revenue_1d → 1d_rev_estimated_max; traffic / visits / visitors / monthly_traffic → monthly_visits; avg_order_value / average_order_value / order_value → aov; traffic_growth_1m → visits_growth_pct_m1; traffic_growth_3m → visits_growth_pct_m3; revenue_change / revenue_momentum / store_revenue_change_30d → visits_growth_pct_m1 (same mapping as the live Explore Shops table when legacy revenue-delta sort was retired).

search_shopify_stores / search_shops filters (all optional unless noted). Names mirror MCP argument names:

Utilisation list_shopify_store_filter_options before filtering by dynamic values (shopify_themes, store_apps, product_taxonomy_l1/l2/l3). Its section argument accepts all, static, themes, apps, product_taxonomy_l1, product_taxonomy_l2, product_taxonomy_l3; pass query to search dynamic option lists.

Intent playbook: “Stores in a niche” → catégorie ou niche = one of the Explore Shops verticals. For fashion/clothing/apparel, use Vêtements. Avoid mot-clé-only niche queries. “Top / biggest by revenue” → sort_by=revenue_1y, sort_order=desc. “New in last N months” → store_created_from / store_created_to inclusive YYYY-MM-DD (both required).

Parity with POST https://app.winninghunter.com/api/shops/explore: MCP uses the same server-side POST keys (rechercher, catégorie, sortingKey, sortingDirection, page, pageSize, includeWlads, …). Argument mapping: mot-clé→rechercher, sort_by→sortingKey, taille→pageSize. Default include_wlads=false → includeWlads=0 (matches the dashboard table request that skips wlads previews).

find_similar_stores_by_image takes image_url (required) plus the same filters as above except mot-clé (similarity replaces text search).

Note: TikTok MCP tools also use a pays argument — there it is marketplace/country context, pas the same field as Shopify merchant pays.

Brand tracker#

Alias : recent / added / newest / latest / date → date_added; alphabetical / alpha / a-z → nom; new / newads → new_ads; trending / momentum → growth.

Exploding Topics#

Aliases for sorting: volume → absolute_volume; exponential → exponent; recent / newest / latest → date_added; trending → growth. catégorie accepts dashboard slugs (e.g. la mode, beauty, skincare, fitness, technology, ai, …) or default for all categories.

mcp_sorting response block#

Every search/list tool that accepts sort_by (or trier/sorting) attaches an mcp_sorting object to the response payload:

{
  "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"
  }
}

If you pass an unknown sort key, mcp_sorting.warning says it fell back to the default — the tool does not error out.

Slice values for detail tools#

Use one of these slice values:

• récupérer_produit_tiktok: detail, history, metrics, créateurs, vidéos
• get_tiktok_shop: detail, history, metrics, produits, vidéos, créateurs, strategy
• get_tiktok_creator: detail, history, metrics, magasins, produits, vidéos
• récupérer_vidéo_TikTok: detail, history, metrics, produits, similar

Two easy mistakes#

1. Trending confusion

   • get_tiktok_trending_products is TikTok Shop product momentum
   • Exploding Topics is separate (search_exploding_topics + get_exploding_topic_detail)

2. Write actions

   • MCP is read-only
   • Favorites, presets, transcripts, and other writes must use REST API

Copy block for AI instructions#

Paste this into agent instructions:

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).
All MCP tools are read-only.
Successful tools/call costs 1 API credit.
If user asks for writes (favorites/presets/transcripts), use REST /api/v1/tiktok-shop/* instead.
When unsure about exact schema, call tools/list first.

Need the full technical detail?#

For full filter semantics and endpoint behavior:

• TikTok Shop filters
• Meta ad library
• Brands
• Shopify store explorer
• Tendances