Criteo MCP server

MCP server, ktorý dáva AI agentovi (Claude Code) tooly na správu Criteo kampaní. Návrh toolov a vysvetlenie Criteo: D:\claude_grizly\criteo\

Čo je v priečinku

Súbor	Načo je
server.py	Samotný MCP server — tooly na kampane, ad sety, kreatívy, audiences, report
criteo_api.py	Komunikácia s Criteo API (token, requesty) — server.py ho používa
prompt-priklady.md	Ťahák: ako zadávať úlohy agentovi v prompte (kampane, kreatívy — čo musí prompt obsahovať)
.env.example	Šablóna konfigurácie — skopíruj ako .env a vyplň
.env	Tvoje tajné kľúče (vytvoríš si sám, NIKDY nezdieľať)
requirements.txt	Zoznam potrebných knižníc

Inštalácia (raz)

Krok 1 — Nainštaluj knižnice

Otvor CMD alebo PowerShell (jedno kde, príkaz je nezávislý od priečinka) a spusti:

D:\Programy\anaconda3\Scripts\pip.exe install fastmcp python-dotenv
# requests uz v Anaconde je, netreba
# ak je vsetko ok, na konci vypise "Successfully installed fastmcp-..." a dalsie balicky
# ak vypise "already satisfied" - uz je nainstalovane, nic netreba, pokracuj dalej

Krok 2 — Vytvor .env s kľúčmi

1. V priečinku D:\claude_grizly\criteo-mcp\ skopíruj súbor .env.example a premenuj kópiu na .env (len .env, bez .example)
2. Otvor .env v Poznámkovom bloku
3. Doplň CRITEO_CLIENT_ID a CRITEO_CLIENT_SECRET — hodnoty máš v .txt súbore stiahnutom z Criteo Partners portálu (Create new key)
4. CRITEO_ADVERTISER_ID zatiaľ môžeš nechať prázdne — test v kroku 3 ti poradí

Krok 3 — Otestuj spojenie (bez MCP)

V CMD/PowerShell spusti:

cd D:\claude_grizly\criteo-mcp
D:\Programy\anaconda3\python.exe server.py --test
# test ide po krokoch a povie ti, co chyba:
#   "Token OK. Appka ma pristup k X inzerentom" + zoznam ID  -> kluce funguju
#       -> ak CRITEO_ADVERTISER_ID v .env este nemas, skopiruj ID zo zoznamu a dopln ho
#   "POZOR: ziadny inzerent - chyba consent krok"            -> Partners portal -> appka
#                                                               -> Generate new URL -> schvalit
#   "CHYBA ... invalid_client"                               -> preklep v client_id/secret v .env
#   "OK - nasiel som X kampani" + zoznam                     -> vsetko kompletne funguje

Krok 4 — Pripoj do Claude Code

V CMD/PowerShell v priečinku projektu, kde chceš server používať (napr. D:\claude_grizly):

cd D:\claude_grizly
claude mcp add criteo -- D:\Programy\anaconda3\python.exe D:\claude_grizly\criteo-mcp\server.py
# vypise potvrdenie "Added stdio MCP server criteo..."
# server sa aktivuje pri dalsom spusteni claude v tomto priecinku

Overenie: spusti claude, napíš /mcp — v zozname má byť criteo so statusom connected.

Použitie

V Claude Code potom stačí písať po ľudsky, agent si tooly zavolá sám:

• „vypíš mi criteo kampane" → list_campaigns
• „aké ad sety má kampaň X a koľko míňajú" → list_ad_sets + get_report
• „vytvor kampaň podľa šablóny..." → create_campaign + create_ad_set

Viac inzerentských účtov

Účet má prístup k viacerým inzerentom (advertiser). Funguje to takto:

• CRITEO_ADVERTISER_ID v .env = default — použije sa, keď v zadaní účet nespomenieš (daj tam ten, s ktorým robíš najčastejšie)
• každý tool má voliteľný parameter advertiser_id — v zadaní stačí povedať „...pre účet XYZ" a agent si ID nájde cez tool list_advertisers a použije ho
• príklad: „vypíš kampane pre všetkých inzerentov" → agent zavolá list_advertisers a potom list_campaigns pre každého
• pozor: CRITEO_DATASET_ID (katalóg) patrí ku konkrétnemu inzerentovi — pri práci s iným účtom agent zistí jeho datasetId cez list_ad_sets

⚠ Write tooly (create/update/start) menia reálny účet a míňajú reálne peniaze. Odporúčanie: nové ad sety nechávaj vypnuté (vytvárajú sa vypnuté automaticky), skontroluj ich v Commerce Growth UI a až potom spusti.

Časté chyby

Prejav	Príčina	Riešenie
invalid_client	preklep v client_id/secret	skopíruj hodnoty z .txt znova, bez medzier
prázdny zoznam kampaní, ale token OK	chýba consent	Partners portál → appka → Generate new URL → schváliť účet
HTTP 401 počas práce	expirovaný token	nič — server si ho obnoví sám; ak sa opakuje stále, over kľúče
HTTP 403	appke chýba oprávnenie (domain permission)	oprávnenia sa po aktivácii nedajú meniť → nová appka + consent
HTTP 400 s popisom poľa	zle poslaný request	prečítaj hlášku — server chyby prenáša doslovne, agent podľa nej opraví volanie
Chýba dataset_id pri create_ad_set	server nepozná ID katalógu	spusti list_ad_sets — existujúce ad sety majú datasetId; hodnotu daj do .env

Kreatívy

Server vie vytvoriť všetky 3 API formáty kreatív (príklady promptov: prompt-priklady.md):

• create_image_creative — statické bannery (upload jpg/png z disku, aj celý priečinok naraz)
• create_dynamic_creative — produktové bannery z feedu (zadávaš len farby, CTA texty, logo)
• create_adaptive_creative — AI bannery z brand podkladov (logo, texty, 6 farieb; voliteľne fotky/video)

Kreatívu potom prepojí s ad setom create_ad. Showcase reklamy cez API nejdú — len ručne v Commerce Growth UI.

Čo zatiaľ nevie / neoverené

• list_audiences, set_ad_set_audience — implementované podľa dokumentácie, ale neoverené na reálnom účte; pri prvom použití môžu potrebovať doladenie (chybové hlášky presne povedia čo)
• create_dynamic_creative, create_adaptive_creative — implementované podľa dokumentácie, na reálnom účte zatiaľ neodskúšané; ak API vráti 400, hláška povie presne ktoré pole treba opraviť