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:

1. --cookies-file FILE (explicit file path)
2. Cached cookies (auto-saved from last extraction)
3. 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:

1. Extract cookies first: $PYTHON scripts/mercadolivre.py cookies
2. Use --visible mode to solve challenges manually if needed
3. Add delays between requests
4. Don't make too many requests in a short period

Exit code 1 on errors, 0 on success.