Skills
skills/quantmind-br/skills/mercadolivre

mercadolivre

SKILL.md

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:

  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

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:

  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.

Weekly Installs
5
Repository
quantmind-br/skills
GitHub Stars
2
First Seen
Mar 1, 2026
Security Audits
Gen Agent Trust HubWarn
SocketWarn
SnykWarn
Installed on
opencode5
gemini-cli5
github-copilot5
codex5
amp5
cline5