Mercado Livre Brazil Search Skill

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

Prerequisites

IMPORTANT: Before running any command, check if the venv exists. If it does not, create it and install all dependencies:

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

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

Quick Reference

Command Description

search -q QUERY

Search products by keyword

search -q QUERY --category informatica

Search within a category

search -q QUERY --condition new

Search only new products

details --mlb-id MLB123

Get full details + variations

details --url URL

Get details from product URL

sellers --mlb-id MLB123

List all sellers for a product

shipping --mlb-id MLB123 --cep 01310100

Estimate shipping by CEP

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

--category

Category slug from categories command (none)

--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

$PYTHON scripts/mercadolivre.py search -q "teclado mecanico" --category informatica

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)", "variations": [ { "id": "COLOR", "label": "Cor", "selected": "Amarelo", "options": [ { "mlb_id": "MLB1027172668", "label": "Amarelo", "url": "https://www.mercadolivre.com.br/.../p/MLB1027172668?picker=true", "price": 4399, "original_price": 7208.99, "stock": "Disponível", "selected": true, "available": true, "thumbnail": "https://http2.mlstatic.com/..." } ] }, { "id": "INTERNAL_MEMORY", "label": "Memória interna", "selected": "128 GB", "options": [ {"mlb_id": "MLB1027172668", "label": "128 GB", "selected": true, "available": true}, {"mlb_id": "MLB1027172669", "label": "256 GB", "selected": false, "available": false}, {"mlb_id": "MLB1027172674", "label": "512 GB", "selected": false, "available": true} ] } ] }

3. List All Sellers for a Product

$PYTHON scripts/mercadolivre.py sellers --mlb-id MLB44601586

$PYTHON scripts/mercadolivre.py sellers --mlb-id MLB44601586 --limit 5

Arguments:

Flag Description Default

--mlb-id

Product MLB ID (required)

--limit

Max sellers to return (all)

Output structure:

{ "success": true, "mlb_id": "MLB44601586", "sellers_count": 2, "sellers": [ { "item_id": "MLB4320299431", "price": 874.74, "original_price": null, "currency": "R$", "installments": "10x R$ 87.47 sem juros", "shipping": "Chegará grátis entre 25/fev e 5/mar dos EUA", "fulfillment": true, "condition": "Novo", "seller": { "name": "Ecomyfy Full", "reputation_level": "5_green", "sales": "+100 vendas", "thermometer": "5/5", "metrics": ["Vendas", "Bom atendimento", "Entrega no prazo"] } } ] }

4. Estimate Shipping by CEP

$PYTHON scripts/mercadolivre.py shipping --mlb-id MLB1027172668 --cep 01310100

$PYTHON scripts/mercadolivre.py shipping --mlb-id MLB44601586 --cep 24350410

Arguments:

Flag Description Default

--mlb-id

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

--url

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

--cep

Brazilian CEP (8-digit zip code) (required)

Output structure:

{ "success": true, "mlb_id": "MLB1027172668", "item_id": "MLB3583764605", "cep": "01310100", "options_count": 3, "options": [ { "method": "Chegará entre terça-feira e quarta-feira no seu endereço", "date": "entre terça-feira e quarta-feira", "price": "Grátis", "free": true, "pickup": false, "extra": "" }, { "method": "Retire a partir de sexta-feira em uma agência Mercado Livre", "date": "a partir de sexta-feira", "price": "Grátis", "free": true, "pickup": true, "extra": "Você tem um ponto de envio a 250 m" } ] }

5. 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" } ] }

6. 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" } }

7. 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://..."} ] }

8. 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

Full product comparison (variations + sellers + shipping)

Get all color/storage options and their MLB IDs

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

Compare prices across all sellers

$PYTHON scripts/mercadolivre.py sellers --mlb-id MLB1027172668

Check total cost with shipping to your location

$PYTHON scripts/mercadolivre.py shipping --mlb-id MLB1027172668 --cep 01310100

Cheapest seller for a product

$PYTHON scripts/mercadolivre.py sellers --mlb-id MLB44601586

Category-scoped search

List available categories

$PYTHON scripts/mercadolivre.py categories

Search within a specific category

$PYTHON scripts/mercadolivre.py search -q "monitor 4k" --category informatica --sort price-asc

Shipping cost comparison across CEPs

$PYTHON scripts/mercadolivre.py shipping --mlb-id MLB1027172668 --cep 01310100 $PYTHON scripts/mercadolivre.py shipping --mlb-id MLB1027172668 --cep 24350410

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.