mcp-brazil-marketplaces

MCP server para buscar anúncios públicos da OLX Brasil e do Mercado Livre Brasil — com bypass automático de bloqueios anti-bot (rotação de User-Agent, warm-up de cookies, retry com backoff, fallback via r.jina.ai, Googlebot UA para o Mercado Livre).

Instalação rápida (zero clone, zero venv)

Use uv — instale uma vez:

curl -LsSf https://astral.sh/uv/install.sh | sh

Depois rode direto:

uvx mcp-brazil-marketplaces

Ou via pip tradicional:

pip install mcp-brazil-marketplaces
mcp-brazil-marketplaces

Configuração no Claude Desktop

Cole o bloco abaixo em claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "marketplaces-br": {
      "command": "uvx",
      "args": ["mcp-brazil-marketplaces"]
    }
  }
}

Se preferir pip em vez de uvx:

{
  "mcpServers": {
    "marketplaces-br": {
      "command": "mcp-brazil-marketplaces"
    }
  }
}

Reinicie o Claude Desktop. As ferramentas olx_buscar_anuncios, olx_detalhe_anuncio e ml_buscar_anuncios ficam disponíveis.

Configuração no Claude Code / Cursor / Continue

Claude Code (CLI):

claude mcp add olx -- uvx mcp-brazil-marketplaces

Cursor (~/.cursor/mcp.json) e Continue (~/.continue/config.json) usam o mesmo bloco JSON do Claude Desktop.

Ferramentas

olx_buscar_anuncios

Busca anúncios na OLX com filtros.

olx_detalhe_anuncio

Retorna detalhes completos de um anúncio da OLX pela URL.

ml_buscar_anuncios

Busca anúncios no Mercado Livre Brasil.

ml_detalhe_anuncio

Retorna detalhes de um anúncio do Mercado Livre.

Diferenças entre as tools

Os limites de página diferem porque cada site retorna ~50 itens por página por padrão e a profundidade útil é menor no ML (resultados ficam ruins após a página 20).

Exemplos de uso

Busque iPhones usados em São Paulo por até R$ 2000, ordenados por menor preço.

Procure Google Pixel 10 Pro XL na OLX e no Mercado Livre. Monte uma tabela comparativa.

Me dê os detalhes do anúncio: https://sp.olx.com.br/...

Desenvolvimento

git clone https://github.com/rodrigopg/mcp-brazil-marketplaces
cd mcp-brazil-marketplaces
python -m venv .venv
.venv/bin/pip install -e .

Rodar o servidor localmente:

.venv/bin/mcp-brazil-marketplaces
# ou
.venv/bin/python -m mcp_brazil_marketplaces

Schema unificado de anúncio

Todas as tools devolvem anúncios com os mesmos campos básicos. Campos específicos por fonte são adicionais.

Comum a OLX e ML:

Específicos da OLX: categoria, bairro, profissional, entrega_olx, propriedades. Específicos do ML: frete, vendedor, atributos.

Envelope da resposta: fonte, total, pagina, por_pagina, url_busca, anuncios, avisos (opcional).

Campo fonte na resposta

Toda resposta inclui um campo fonte no envelope (e em cada anúncio) indicando a origem dos dados:

Verifique sempre fonte antes de tomar decisão crítica — payloads olx_jina vêm de markdown reduzido, com menos campos (sem propriedades, sem entrega_olx, sem timestamps precisos). Para desabilitar o fallback Jina, defina MCP_BR_DISABLE_JINA=1 (ver abaixo).

Variáveis de ambiente

Todos os parâmetros operacionais podem ser ajustados via env (com clamp seguro):

Privacidade e considerações

• Fallback via r.jina.ai: quando a OLX bloqueia requisições diretas, o servidor reenvia a URL pelo serviço público r.jina.ai para obter o conteúdo em markdown. Isso significa que a Jina AI tem acesso ao log das URLs consultadas durante o fallback. Para desabilitar:

  export MCP_BR_DISABLE_JINA=1

  Com a flag ativa, falhas de bypass retornam erro em vez de consultar terceiros. Toda resposta inclui o campo fonte (olx, olx_jina, ml) para que você saiba a origem dos dados.

• Mercado Livre — Googlebot UA: o scraper do ML usa User-Agent: Googlebot/2.1 para contornar a página de challenge anti-bot. ML pode banir IPs que detectem o spoof; use moderadamente. Para desabilitar o spoof, defina MCP_BR_ML_USER_AGENT com um UA real (esperado: ML retornará challenge e a tool dará lista vazia).

• Scraping de dados públicos: este servidor consulta dados públicos da OLX e do Mercado Livre. Use com responsabilidade e respeite os termos de uso de cada site.

Roadmap

Próximos passos rastreados em ROADMAP.md + milestones do GitHub. Há 31 itens organizados em 5 milestones (v0.4 → v1.0 + future).

Release

Releases para o PyPI são automatizados via Trusted Publishing (OIDC) — sem tokens armazenados. Workflow .github/workflows/release.yml dispara em tags v*.

Para cortar uma release:

# bump em pyproject.toml + olx_mcp/__init__.py
git commit -am "release v0.4.0"
git tag v0.4.0
git push && git push --tags

O GitHub Actions builda wheel/sdist, valida que a tag bate com pyproject.toml, e publica via OIDC no PyPI.

Licença

MIT