olx-mcp (vibe coded nije me briga)

MCP server za OLX.ba API. Omogućava Claudeu (i drugim MCP klijentima) da pretražuje OLX, objavljuje i uređuje oglase, upravlja slikama i sponzorstvima. 36 alata koji pokrivaju sve endpointe iz zvanične dokumentacije, plus pretragu oglasa.

Kako izgleda

Nekoliko primjera šta možete tražiti kad je server dodan:

Related MCP server: mcp-brazil-marketplaces

Instalacija

claude mcp add olx -- npx -y @omznc/olx-mcp

To je sve. Prvi put kad neki alat zatraži prijavu, server zatraži korisničko ime i lozinku kroz sam MCP klijent (Claude Code prikaže prozorčić), razmijeni ih za token, sačuva ga i nastavi prekinuti poziv. Nema posebne login komande ni restarta.

Ako vam više odgovara terminal, ili klijent ne podržava taj prozorčić:

npx -y @omznc/olx-mcp login

Treća opcija je bez ikakve prijave: podatke stavite u konfiguraciju samog servera.

claude mcp add olx -e OLX_USERNAME=vase.ime -e OLX_PASSWORD=vasa.lozinka -- npx -y @omznc/olx-mcp

Server se tada prijavi sam pri prvom pozivu i sam obnovi token kad istekne. Razlika je gdje stoji lozinka: ovako ostaje zapisana u konfiguraciji MCP klijenta u čitljivom obliku, dok prozorčić i login sačuvaju samo token. Sva tri načina rade, birajte po tome šta vam više odgovara.

Radi sa Node.js 18+ ili Bunom. npx je samo najčešće dostupan; ako koristite Bun, bunx radi isto tako.

Server je običan stdio MCP server, pa u konfiguraciju klijenta ide:

{
  "mcpServers": {
    "olx": {
      "command": "npx",
      "args": ["-y", "@omznc/olx-mcp"]
    }
  }
}

Isto vrijedi i ovdje: klijenti koji podržavaju elicitation sami prikažu prozorčić za prijavu na prvom alatu koji je traži. Ako ne podržavaju, prijavite se iz terminala (npx -y @omznc/olx-mcp login) ili dodajte podatke u env iste konfiguracije:

{
  "mcpServers": {
    "olx": {
      "command": "npx",
      "args": ["-y", "@omznc/olx-mcp"],
      "env": {
        "OLX_USERNAME": "vase.ime",
        "OLX_PASSWORD": "vasa.lozinka"
      }
    }
  }
}

Ažuriranje

Paket je na npm-u, pa npx -y @omznc/olx-mcp sam povuče zadnju objavljenu verziju. Dovoljno je restartovati MCP klijenta.

Ako npx drži staru verziju u cacheu, prisilite tačnu:

npx -y @omznc/olx-mcp@latest

Prijava ostaje sačuvana; token je u auth.json, ne u cacheu.

Prijava

Prijava kroz MCP klijent (MCP „elicitation”) je podrazumijevani put i traži se tek kad zatreba, na prvom alatu koji je ne može bez nje:

1. Alat poput olx_me naiđe na to da nema tokena ni env varijabli.

2. Server pošalje elicitation/create, klijent prikaže polja za korisničko ime i lozinku.

3. Podaci idu na POST /auth/login, token se sačuva u auth.json, prekinuti poziv se ponovi.

Lozinka pri tome ide MCP kanalom do ovog procesa, a ne kao argument alata, pa je model ne vidi u transkriptu. Ali ne kontrolišemo šta klijent radi sa onim što ste ukucali u svoj prozorčić — ako želite da lozinka ostane strogo lokalna, koristite login iz terminala.

Isto se dešava kad sačuvani token istekne: umjesto greške dobijete prozorčić i poziv se nastavi.

Klijent koji ne najavi elicitation sposobnost nikad ne dobije taj zahtjev i vidi običnu grešku sa uputom da se pokrene login. OLX_NO_ELICIT=1 isključuje prozorčić i kad ga klijent podržava.

Iz terminala

npx -y @omznc/olx-mcp login     # traži korisničko ime i lozinku
npx -y @omznc/olx-mcp status    # provjeri da li prijava radi
npx -y @omznc/olx-mcp logout    # obriši sačuvani token

Lozinka se ne ispisuje dok se kuca i nigdje se ne čuva. Sačuva se samo token koji OLX vrati:

Na Linuxu i macOS-u fajl dobija dozvole 600, pa ga čita samo vaš korisnik.

Prijavljujte se kroz prozorčić, iz terminala ili preko varijabli okruženja ispod, a ne kroz olx_login alat u razgovoru: argumenti alata se zapisuju u historiju razgovora, pa bi lozinka završila tamo.

Varijable okruženja

Idu u env konfiguracije MCP servera, ili u okruženje procesa kod CI-ja i sličnog. Imaju prioritet nad sačuvanim tokenom:

Alati

Autentikacija: olx_login, olx_logout, olx_auth_status

Pretraga: olx_search_listings

Oglasi: olx_get_listing, olx_create_listing, olx_update_listing, olx_publish_listing, olx_delete_listing, olx_finish_listing, olx_hide_listing, olx_unhide_listing, olx_refresh_listing, olx_refresh_limits, olx_listing_limits, olx_upload_listing_images, olx_delete_listing_image, olx_set_main_listing_image

Korisnici: olx_me, olx_user_listings (aktivni / završeni / neaktivni / istekli / skriveni)

Kategorije: olx_categories, olx_category, olx_category_attributes, olx_category_brands, olx_category_brand_models, olx_suggest_category, olx_find_category

Lokacije: olx_cities, olx_city, olx_countries, olx_country_states, olx_canton_cities

Sponzorstva: olx_sponsor_price, olx_sponsor_listing, olx_set_discount, olx_finish_discount

Samo olx_search_listings radi bez prijave; sve ostalo traži token.

Objavljivanje oglasa

flowchart LR
  A["olx_suggest_category<br/>nađi category_id"] --> B["olx_category_attributes<br/>koji atributi trebaju"]
  B --> C["olx_create_listing<br/>status DRAFT"]
  C --> D["olx_upload_listing_images<br/>fajlovi i/ili URL-ovi"]
  D --> E["olx_publish_listing<br/>oglas je javan"]
  C -.->|"olx_update_listing nad DRAFT-om ga objavi"| E

1. olx_suggest_category: nađite category_id na osnovu opisa artikla.

2. olx_category_attributes: pogledajte koje atribute ta kategorija traži.

3. olx_create_listing: vraća id novog oglasa, status DRAFT.

4. olx_upload_listing_images: lokalni fajlovi i/ili URL-ovi slika.

5. olx_publish_listing: oglas ide live.

DRAFT nije privatan draft. Provjereno na live API-ju: prvi olx_update_listing nad draftom ga objavi. Status pređe u active i oglas je javno vidljiv, isto kao da je pozvan olx_publish_listing. Zato oglas pravite tek kad je sadržaj gotov, a ne uz plan da se popravi poslije.

Pažnja: troši novac ili je nepovratno

• olx_sponsor_listing skida sredstva sa OLX računa. Prvo provjerite cijenu sa olx_sponsor_price.

• olx_refresh_listing je besplatan samo unutar limita iz olx_refresh_limits.

• olx_delete_listing se ne može poništiti; olx_hide_listing i olx_finish_listing mogu.

• olx_publish_listing čini oglas javno vidljivim na OLX-u.

• olx_update_listing nad DRAFT oglasom ga takođe objavi, vidi gore.

Svaki alat nosi MCP anotacije (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), pa MCP klijent može sam odlučiti šta pušta bez pitanja, a šta ne. olx_delete_listing, olx_delete_listing_image, olx_sponsor_listing i olx_logout su označeni kao destruktivni. Opisi alata uz to upozoravaju model da prvo pita korisnika, ali ni jedno ni drugo nije tehnička zabrana.

Napomene

• GET /search (iza olx_search_listings) nije dio zvanične dokumentacije. To je endpoint koji koristi sam OLX sajt, provjeren na live API-ju. Ne traži prijavu i može se promijeniti bez najave. Svi ostali alati odgovaraju dokumentovanim endpointima.

• Alati koji vraćaju velike odgovore (olx_search_listings, olx_user_listings, olx_get_listing, olx_me, olx_cities, olx_categories, olx_category_attributes) daju sažetak, da ne troše kontekst modela. Svaki od njih prima full: true za sirovi OLX odgovor.

• OLX vraća 403 ili 404 za endpointe za koje račun nema dozvolu, pa 404 ne znači uvijek da resurs ne postoji.

• Zahtjevi imaju timeout (OLX_TIMEOUT_MS, podrazumijevano 30s). 429 i mrežne greške se ponove sa kratkim backoffom; 5xx se ponovi samo za GET, jer je upis možda već prošao.

• Ako OLX odbije token, a postavljeni su OLX_USERNAME + OLX_PASSWORD, server se sam ponovo prijavi i ponovi zahtjev. Sa samo OLX_TOKEN ili sačuvanim tokenom to nije moguće, pa treba ponovo olx-mcp login.

• Sve cijene su u KM (BAM).

• Ovo je nezvaničan projekat i nije povezan sa OLX-om.

Razvoj

Za rad na projektu treba Bun.

bun install
bun run start        # pokreni server iz src/
bun test             # pokreće server preko stdio i testira ga kao pravi MCP klijent
bun run typecheck
bun run build        # bundluje src/ u dist/index.js

bun test prvo bundluje src/ u dist/index.js, jer dio testova pokreće baš taj bundle pod Nodeom. dist/ se ne commituje; objavljuje se na npm iz CI-ja kad se gurne v* tag.

Testovi koji zovu live OLX API su isključeni po defaultu, da pad na OLX-ovoj strani ne obara nepovezan PR:

OLX_LIVE_TESTS=1 bun test

Licenca

MIT