Mercado Livre Brazil Search Skill

Search and analyze products on Mercado Livre Brazil (mercadolivre.com.br) via CLI using Camoufox stealth browser.

Prerequisites

cd <SKILL_DIR> python3 -m venv .venv .venv/bin/pip install "camoufox[geoip]" playwright beautifulsoup4 lxml browser-cookie3 .venv/bin/python3 -m camoufox fetch

PYTHON=<SKILL_DIR>/.venv/bin/python3

Quick Reference

Command Description

search -q QUERY

Search products by keyword

search -q QUERY --condition new

Search only new products

details --mlb-id MLB123

Get full details of a product

details --url URL

Get details from product URL

reviews --mlb-id MLB123

Get product reviews

seller --mlb-id MLB123

Get seller reputation info

categories

List all categories

cookies

Extract & verify ML cookies from browser

cookies --export FILE

Export cookies to JSON file

Script Location

<SKILL_DIR>/scripts/mercadolivre.py

Commands

1. Search Products

$PYTHON scripts/mercadolivre.py search -q "iphone 15" --limit 5

Arguments:

Flag Short Description Default

--query

-q

Search term (required)

--condition

Filter: new , used

(all)

--page

Page number (1-based) 1

--min-price

Minimum price in BRL (none)

--max-price

Maximum price in BRL (none)

--free-shipping

Show only free shipping products false

--sort

Sort: relevance , price-asc , price-desc , newest

relevance

--limit

Max results to return 50

--visible

Show browser window (useful for debugging) false

Search with filters:

$PYTHON scripts/mercadolivre.py search -q "notebook" --min-price 2000 --max-price 5000

$PYTHON scripts/mercadolivre.py search -q "headphone" --condition new --free-shipping

$PYTHON scripts/mercadolivre.py search -q "kindle" --sort price-asc --limit 10

$PYTHON scripts/mercadolivre.py search -q "macbook" --page 2

Output structure:

{ "success": true, "query": "iphone 15", "url": "https://lista.mercadolivre.com.br/iphone+15...", "page": 1, "total_results": 530, "results_count": 5, "results": [ { "mlb_id": "MLB1027172671", "title": "Apple iPhone 15 (128 GB) - Verde - Distribuidor Autorizado", "url": "https://www.mercadolivre.com.br/.../p/MLB1027172671", "price": "R$ 3.959", "price_value": 3959.0, "original_price": "R$ 7.208", "installments": "ou R$4.399 em 10x R$439,90 sem juros", "condition": "", "shipping": "Chegará grátis amanhã", "free_shipping": true, "seller": "Apple", "image": "https://http2.mlstatic.com/..." } ] }

2. Get Product Details

$PYTHON scripts/mercadolivre.py details --mlb-id MLB1027172671

$PYTHON scripts/mercadolivre.py details --url "https://www.mercadolivre.com.br/.../p/MLB1027172671"

Output structure:

{ "success": true, "mlb_id": "MLB1027172671", "title": "Apple iPhone 15 (128 GB) - Verde - Distribuidor Autorizado", "price": "R$ 3.959,10", "price_value": 3959.1, "original_price": "R$ 7.208", "original_price_value": 7208.0, "discount": "45% OFF no Pix ou Saldo no Mercado Pago", "installments": "em 10x R$ 439,90 sem juros", "condition": "Novo", "sold_count": "+5mil vendidos", "rating": "4.9", "reviews_count": "(39940)", "images": ["https://http2.mlstatic.com/..."], "seller": { "name": "Mercado Livre Eletronicos", "link": "", "official_store": "Loja oficial Apple", "sales_count": "+1 M vendas" }, "shipping": "Frete grátis", "free_shipping": true, "fulfillment": true, "features": [ {"key": "Marca", "value": "Apple"}, {"key": "Linha", "value": "iPhone 15"}, {"key": "Modelo", "value": "iPhone 15"} ], "description": "Full product description text...", "stock": "(+10 disponíveis)" }

3. Get Product Reviews

$PYTHON scripts/mercadolivre.py reviews --mlb-id MLB1027172671

$PYTHON scripts/mercadolivre.py reviews --url "https://www.mercadolivre.com.br/.../p/MLB1027172671" --limit 10

Arguments:

Flag Description Default

--mlb-id

Product MLB ID (one of mlb-id/url required)

--url

Product URL (one of mlb-id/url required)

--limit

Max reviews to return 20

Output structure:

{ "success": true, "mlb_id": "MLB1027172671", "summary": { "average": "4.9", "total_reviews": "13.148 comentários" }, "reviews_count": 5, "reviews": [ { "rating": "5/5", "body": "Aparelho bom. Mas deveria sim vim com o carregador...", "date": "14 fev. 2024", "helpful": "17897" } ] }

4. Get Seller Info

$PYTHON scripts/mercadolivre.py seller --mlb-id MLB1027172671

$PYTHON scripts/mercadolivre.py seller --url "https://www.mercadolivre.com.br/.../p/MLB1027172671"

Output structure:

{ "success": true, "mlb_id": "MLB1027172671", "seller": { "name": "Mercado Livre Eletronicos", "link": "", "official_store": "Loja oficial Apple", "sales_count": "+1 M vendas", "metrics": [], "thermometer": "5/5", "location": "São Paulo" } }

5. List Categories

$PYTHON scripts/mercadolivre.py categories

$PYTHON scripts/mercadolivre.py categories -s "celular"

Arguments:

Flag Short Description Default

--search

-s

Filter categories by name (all)

Output structure:

{ "success": true, "count": 35, "categories": [ {"id": "MLB1051", "name": "Celulares e Telefones", "url": "https://..."}, {"id": "MLB1648", "name": "Computação", "url": "https://..."} ] }

6. Extract & Verify Cookies

Automatically extracts Mercado Livre cookies from the user's browser (Chromium, Chrome, Brave, Firefox, Edge).

$PYTHON scripts/mercadolivre.py cookies

$PYTHON scripts/mercadolivre.py cookies --browser brave

$PYTHON scripts/mercadolivre.py cookies --export ~/ml-cookies.json

Output:

{ "success": true, "browser": "chromium", "cookie_count": 45, "auth_ok": true, "cache_file": "<SKILL_DIR>/.cookies_cache.json" }

Cookie priority chain:

• --cookies-file FILE (explicit file path)

• Cached cookies (auto-saved from last extraction)

• Auto-extract from browser (tries chromium, chrome, brave, firefox, edge, opera)

Common Workflows

Price comparison

$PYTHON scripts/mercadolivre.py search -q "macbook air m3" --sort price-asc --limit 10

Product research

$PYTHON scripts/mercadolivre.py details --mlb-id MLB1027172671 $PYTHON scripts/mercadolivre.py reviews --mlb-id MLB1027172671 --limit 10 $PYTHON scripts/mercadolivre.py seller --mlb-id MLB1027172671

Deal hunting

$PYTHON scripts/mercadolivre.py search -q "echo dot" --free-shipping --sort price-asc

New vs used comparison

$PYTHON scripts/mercadolivre.py search -q "iphone 14" --condition new --sort price-asc --limit 5 $PYTHON scripts/mercadolivre.py search -q "iphone 14" --condition used --sort price-asc --limit 5

Technical Notes

• Uses Camoufox (stealth Firefox via Playwright) for all page fetching

• Runs in headless mode by default. Use --visible to see the browser

• GeoIP enabled for proper timezone/locale matching

• Retry logic: 2 retries with exponential delay on failures or blocked pages

• Cloudflare detection: automatically detects challenge pages in responses

• Cookies improve reliability - extract them with cookies command first

• Each search page returns ~50 results (Mercado Livre's default)

• MLB ID is the unique product identifier (e.g., MLB1027172671)

• All output is JSON to stdout, errors to stderr, exit code 0/1

• Price values are parsed as floats (e.g., "R$ 4.499,00" -> 4499.0)

• Search URLs: https://lista.mercadolivre.com.br/{query}

• Product URLs: https://www.mercadolivre.com.br/.../p/MLB{id}

• Pagination uses offset: Desde{offset} in URL

Error Handling

Errors return JSON with an error field to stderr:

{"success": false, "error": "Fetch failed for https://...", "details": "Timeout"}

If Cloudflare serves a challenge page, the response includes "blocked": true :

{"success": true, "blocked": true, "results_count": 0, "results": []}

Tips to avoid blocking:

• Extract cookies first: $PYTHON scripts/mercadolivre.py cookies

• Use --visible mode to solve challenges manually if needed

• Add delays between requests

• Don't make too many requests in a short period

Exit code 1 on errors, 0 on success.