OLX MCP

An AI-optimized Model Context Protocol (MCP) server for searching, scraping, market price analysis, deal evaluation, and negotiation preparation on OLX marketplaces.

Strictly focused on Poland (olx.pl) and Ukraine (olx.ua).

Features

• AI Token Efficient: Bounded compact summaries for batch searches, server-side percentiles and deal calculations, and optional single-part JPEG contact sheets for image analysis.
• Deep Extraction: Extracts structured data from Redux __PRERENDERED_STATE__, Next.js __NEXT_DATA__, JSON-LD, and fallback microdata.
• Public Seller Intelligence: Retrieves seller type (private vs business), account registration date, badges, ratings, and phone availability to empower informed negotiations.
• Market Analysis & Deal Scoring: Computes P10, P25, P50, P75, P90 price percentiles, filters broken/parts items, removes IQR outliers, and scores bargain discounts below market median.
• Negotiation Preparation: Calculates seller leverage based on days on market and market median, suggests opening/closing offers, and drafts polite localized messages in Polish (pl), Ukrainian (uk), and English (en).
• Resilient Transport: Modern HTTP/2 with browser TLS fingerprints, CloudFront WAF header bypass, retries with exponential backoff, and host circuit breakers.
• Persistent SQLite Engine: Caches observations, price history trends, category filter schemas, and polls saved searches with automatic diff alerts (added, removed, priceChanged).

Documentation

• Getting started and configuration
• MCP tools, resources, and prompts
• Architecture and development
• Security and operational limits

Development

The runtime is a self-contained Go 1.27 binary with no external C or Node.js dependencies:

go test ./...
go run ./cmd/olx-mcp

The server communicates over MCP stdio by default. Set configuration through environment variables; see .env.example.

An optional Streamable HTTP endpoint is enabled with OLX_MCP_HTTP_PORT and requires Authorization: Bearer <OLX_MCP_AUTH_TOKEN>. /metrics exposes Prometheus-compatible counters.

Connecting Your OLX Account (For Chat & Negotiations)

Connecting your OLX account is easy via three methods:

1. CLI Command:

   # Save token directly to local SQLite
   ./olx-mcp auth --market pl --token "YOUR_BEARER_TOKEN"
   # Check status
   ./olx-mcp auth --market pl --status
   

2. MCP Tool: Call olx_auth_set_token(token="YOUR_BEARER_TOKEN", market="pl").
3. Environment Variable: Set OLX_AUTH_TOKEN_PL="YOUR_BEARER_TOKEN" or OLX_AUTH_TOKEN_UA="YOUR_BEARER_TOKEN".

How to get your token: Open olx.pl or olx.ua in Chrome/Firefox, log in, press F12 -> Network tab -> click any request to api.olx.pl/v1/... -> copy the Authorization: Bearer <TOKEN> header value.

Multimodal Photo Forwarding & Defect Auditing

To spot subtle scratches or screen wear that sellers omit from descriptions:

• Call olx_inspect_listing_images(idOrUrl="...", maxImages=4) to receive full-resolution photos side-by-side with an inspection checklist.
• Call olx_get_listing(idOrUrl="...", imageMode="individual") for full details plus individual images.
• Detected visual flaws can be passed to olx_prepare_negotiation(..., visualDefects=["micro-scratches on lid"]) to factor them into leverage points, opening offer discounts, and polite drafted messages!

WebUI Dashboard (Filter & Deal Management)

Manage your safety rules, inspect active negotiations, and configure tokens with a built-in React + Vite WebUI:

# Run standalone WebUI server on port 8080
./olx-mcp web --port 8080

# Or run MCP stdio with background WebUI enabled
OLX_WEB_PORT=8080 ./olx-mcp

WebUI Features:

• Safety & Filter Rules: Configure minimum seller account age (14d, 30d / 1 month, 60d), OLX delivery requirement, maximum risk tolerance, and blocked scam keywords (blik, zaliczka, etc.).
• Deals & Negotiations Tracker: Live dashboard showing status of offers, asking vs agreed prices, notes, one-click phone reveal, and direct OLX links.
• Account & Auth: Switch between olx.pl and olx.ua markets, inspect token status, and paste new Bearer tokens.

Autonomous Buyer MCP Tools

Tool	Description
olx_search_listings	Search listings with filters, pagination, and token-efficient compact summaries.
olx_get_listing	Fetch complete listing with clean description, seller profile, and photos (compact contact sheet or individual high-res).
olx_inspect_listing_images	Forward high-resolution candidate photos to AI vision for cosmetic defect auditing.
olx_parse_specs	Extract hardware specifications (Apple Silicon chip M1-M5, RAM, SSD, battery health %, cycle count, keyboard layout) from text.
olx_assess_risk	Scan advert and seller for scam red flags, new account penalty, blocked payment terms, and price anomalies.
olx_find_deals	Find high-value bargains significantly below market median, excluding broken/parts items.
olx_prepare_negotiation	Analyze seller leverage, compute fair offers, and draft localized Polish/Ukrainian/English negotiation messages factoring in visual defects.
olx_track_deal	Track an active negotiation in SQLite (status, asking price, current offer, agreed price, notes).
olx_list_deals	Query tracked negotiations by market and status.
olx_deal_summary	Generate a high-conviction decision card and one-click purchase URL for user approval.
olx_get_settings	Retrieve active safety thresholds and filter rules.
olx_update_settings	Update safety thresholds (min seller age, delivery requirement, blocked keywords).
olx_reveal_phone	Unmask seller phone number on authenticated accounts.
olx_analyze_market	Server-side percentiles, bargain scoring, IQR outlier removal, and market confidence directly from query or pre-fetched listings.
olx_compare_listings	Side-by-side comparison of listing prices, parameters, and metadata.
olx_list_markets	List supported markets (pl, ua) and native currencies.
olx_search_markets	Search Polish and Ukrainian markets concurrently.
olx_search_markets_normalized	Cross-market search with audited caller-supplied currency rates.
olx_get_listing_history	Historical price observations for a listing.
olx_get_category_filters	Common category filter definitions.
olx_get_category_filter_schema	Discover and cache category filter schema for a market.
olx_save_search	Create or replace a persistent saved search.
olx_get_saved_search	Read a saved search configuration.
olx_list_saved_searches	List all saved searches.
olx_set_saved_search_enabled	Enable or disable a saved search.
olx_delete_saved_search	Delete a saved search.
olx_poll_saved_search	Poll a saved search and return diffs (added, removed, priceChanged).
olx_notify_webhook	Deliver signed webhooks with SSRF prevention and durable retry queue.
olx_auth_status	Check if an active OLX user account token is configured.
olx_auth_set_token	Save Bearer token or session for a market.
olx_chat_list_threads	List active conversations and chat threads with sellers.
olx_chat_get_thread	Read conversation message history with a seller.
olx_chat_send_message	Send a response message to a seller.
olx_chat_start_thread	Initiate a new conversation on an advert with an opening offer.
olx_chat_poll_updates	Poll active chat conversations for seller replies and status diffs.

Production Container

Build and run using Docker Compose:

docker compose build
docker compose run --rm olx-mcp