Skip to main content
Glama
rodrigopg

mcp-brazil-marketplaces

by rodrigopg

mcp-brazil-marketplaces

PyPI version Python versions PyPI downloads CI License: MIT Ruff

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

Related MCP server: olx-mcp

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 (plugin, recomendado):

/plugin marketplace add rodrigopg/claude-plugins
/plugin install mcp-brazil-marketplaces@rodrigopg

Claude Code (CLI, sem plugin):

claude mcp add marketplaces-br -- 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.

Parâmetro

Tipo

Obrigatório

Descrição

query

string

Sim

Termo de busca

estado

string

Não

Sigla do estado (sp, rj, go…)

categoria

string

Não

Slug de categoria (celulares, imoveis…)

preco_min

int

Não

Preço mínimo em reais

preco_max

int

Não

Preço máximo em reais

ordenar

string

Não

relevance | price | date

pagina

int

Não

Página (1–50)

olx_detalhe_anuncio

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

Parâmetro

Tipo

Obrigatório

Descrição

url

string

Sim

URL completa do anúncio na OLX

ml_buscar_anuncios

Busca anúncios no Mercado Livre Brasil.

Parâmetro

Tipo

Obrigatório

Descrição

query

string

Sim

Termo de busca

preco_min

int

Não

Preço mínimo em reais

preco_max

int

Não

Preço máximo em reais

condicao

string

Não

novo | usado

estado

string

Não

Sigla UF para filtragem pós-scraping (ver avisos)

pagina

int

Não

Página (1–20, 50 itens cada)

ml_detalhe_anuncio

Retorna detalhes de um anúncio do Mercado Livre.

Parâmetro

Tipo

Obrigatório

Descrição

url

string

Sim

URL completa do anúncio (*.mercadolivre.com.br ou *.mercadolibre.com)

Diferenças entre as tools

Aspecto

OLX

Mercado Livre

Páginas máx.

50

20

Ordenação

relevance | price | date

Não suportada (ML não aceita via URL pública)

Filtro condicao

N/A

Heurística pós-scraping no título

Filtro estado

Nativo na URL

Heurística pós-scraping (frequentemente vazio)

Detalhe de anúncio

olx_detalhe_anuncio

ml_detalhe_anuncio

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:

Campo

Tipo

Descrição

fonte

string

olx | olx_jina | ml

id

int | string

ID do anúncio

titulo

string

Título

preco

string

Preço formatado (R$ X)

localizacao

string | null

Cidade/bairro/UF (pode ser null no ML)

data

string | null

Data legível (null no ML — não exposta nos cards)

url

string

URL canônica do anúncio

imagem

string | null

URL da imagem principal

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:

Valor

Significado

olx

Scraping direto da OLX via httpx (caminho preferido)

olx_jina

Fallback: a OLX bloqueou e usamos r.jina.ai como proxy reader

ml

Scraping direto do Mercado Livre via UA Googlebot

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

Variável

Default

Faixa

Descrição

MCP_BR_REQUEST_TIMEOUT

25.0

1.0–300.0

Timeout HTTP em segundos

MCP_BR_MAX_RETRIES

4

0–20

Tentativas no fetcher OLX (retry + troca de perfil)

MCP_BR_WARMUP_PROBABILITY

0.7

0.0–1.0

Chance de warm-up da homepage antes do search

MCP_BR_DISABLE_JINA

0

0/1

Desabilita fallback via r.jina.ai

MCP_BR_LOG_LEVEL

WARNING

DEBUG/INFO/WARNING/ERROR

Nível do logger mcp_brazil_marketplaces

MCP_BR_ML_USER_AGENT

(Googlebot)

qualquer string

Sobrescreve UA usado no Mercado Livre. Use se o spoof de Googlebot for inaceitável — ML geralmente devolverá a página anti-bot e a tool retornará lista vazia.

MCP_BR_RATE_LIMIT_CONCURRENCY

2

1–16

Máx. de requests HTTP simultâneos

MCP_BR_RATE_LIMIT_MIN_GAP

0.5

0.0–30.0

Gap mínimo em segundos entre requests ao mesmo host. 0 desabilita

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

Available Tools

4 tools
ml_buscar_anunciosA
Read-onlyIdempotent

Busca anúncios no Mercado Livre Brasil.

Args: params (BuscarMLInput): - query (str): Termo obrigatório. - preco_min/preco_max (Optional[int]): Faixa de preço em reais. - estado (Optional[str]): Filtro pós-scraping por sigla UF (heurística). - condicao (Optional[str]): 'novo' ou 'usado'. - pagina (int): Página (50 itens por página).

Returns: str: JSON com lista de anúncios (titulo, preco, frete, atributos, url, imagem).

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate read-only, idempotent, non-destructive. The description adds behavioral context beyond annotations, warning about heuristic filters (estado, condicao) and their limitations (best-effort, frequent empty results). This helps the agent understand reliability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a structured Args/Returns format. Every sentence adds value, including warnings. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple parameters, heuristics, output schema), the description covers all necessary aspects: purpose, parameters, return format, and caveats. Annotations cover safety. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description fully explains each parameter: query required, price range, state (with warning), condition, and page. It adds meaning about post-scraping heuristics and unit (reais).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches for listings on Mercado Livre Brazil, a specific verb+resource. It distinguishes from siblings like ml_detalhe_anuncio (details) and olx_buscar_anuncios (different platform).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. While sibling names suggest context, there is no explicit guidance on when to prefer this tool or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ml_detalhe_anuncioA
Read-onlyIdempotent

Obtém detalhes de um anúncio do Mercado Livre a partir da URL.

Args: params (DetalheMLInput): - url (str): URL completa do anúncio.

Returns: str: JSON com campos comuns (id, titulo, preco, url, fonte) + descricao, imagens, vendedor. Em caso de erro: {"erro": "..."}.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds value by specifying the return format (JSON with common fields, description, images, seller, and error handling), which is beyond the annotations. It does not mention rate limits or authentication, but for a read-only tool this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences for the main purpose, plus structured 'Args' and 'Returns' sections. Every part adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool (1 param, no nested objects) with an output schema available, the description covers the purpose, input parameter, and return format (including error handling). It is complete given the context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description restates the 'url' parameter and its purpose, which is already documented in the input schema. With schema description coverage at 0% (implying schema lacks descriptions, though the schema actually has one), the description adds minimal new meaning. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves details of a Mercado Livre listing from a URL, using the verb 'Obtém' (gets) and specifying the resource and platform. It is implicitly differentiated from siblings like ml_buscar_anuncios (search) and olx_detalhe_anuncio (OLX platform).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, such as when to search vs. get details, or any prerequisites (e.g., valid URL format). It only states the action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

olx_buscar_anunciosA
Read-onlyIdempotent

Busca anúncios públicos na OLX Brasil com filtros de texto, estado, categoria, preço e ordenação.

Retorna lista paginada de anúncios com título, preço, localização, data, URL e propriedades extras.

Args: params (BuscarAnunciosInput): - query (str): Termo de busca obrigatório. - estado (Optional[str]): Sigla do estado ('sp', 'go', etc.). Padrão: todo Brasil. - categoria (Optional[str]): Slug de categoria OLX. Ex: 'informatica-e-acessorios'. - preco_min (Optional[int]): Preço mínimo em reais. - preco_max (Optional[int]): Preço máximo em reais. - ordenar (str): 'relevance' | 'price' | 'date'. Padrão: 'relevance'. - pagina (int): Número da página (1–50). Padrão: 1.

Returns: str: JSON com campos: - total (int): Total de anúncios encontrados. - pagina (int): Página atual. - por_pagina (int): Anúncios por página. - url_busca (str): URL utilizada na busca. - anuncios (list): Lista de anúncios com id, titulo, preco, categoria, localizacao, bairro, data, url, imagem, profissional, entrega_olx, propriedades.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds details on pagination limits (1-50), ordering options, and price range, but does not mention rate limits or authentication. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear purpose statement, followed by parameter and return lists. It is informative but slightly verbose; could be more concise without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of the tool (multiple filters, pagination, ordering), the description covers all essential aspects, including the return format. It is fully adequate for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds value beyond the input schema by providing example values for each parameter (e.g., 'sp', 'notebook', 500). The schema already has descriptions for each property, but the description consolidates and contextualizes them effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches public ads on OLX Brazil with various filters and returns a paginated list. It distinguishes from sibling tools (ml_buscar_anuncios, ml_detalhe_anuncio, olx_detalhe_anuncio) by specifying the platform and action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly compare with sibling tools or state when to use this tool vs alternatives. However, the platform-specific name and description imply it's for OLX searches, providing implicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

olx_detalhe_anuncioA
Read-onlyIdempotent

Obtém detalhes completos de um anúncio específico da OLX a partir da URL.

Args: params (DetalheAnuncioInput): - url (str): URL completa do anúncio na OLX.

Returns: str: JSON com campos: - id (int): ID do anúncio (list_id). - titulo (str): Título do anúncio. - descricao (str): Descrição completa (HTML removido). - preco (str): Preço formatado. - categoria (str): Categoria principal. - subcategoria (str): Subcategoria. - estado (str): UF do anúncio. - municipio (str): Cidade. - bairro (str): Bairro. - vendedor (str): Nome do vendedor. - profissional (bool): Se é anunciante profissional. - data (str): Data de publicação formatada. - imagens (list[str]): Lista de URLs das imagens. - propriedades (dict): Atributos específicos da categoria. - url (str): URL canônica do anúncio.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description reveals that the description field has HTML removed and lists all returned fields, adding detail beyond the readOnly and idempotent annotations. No contradictions are present.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with separate Args and Returns sections, and the purpose is front-loaded. It is not overly verbose for the detail provided.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description comprehensively covers input and output fields, and annotations are present. Missing error handling details but adequate for selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The 'url' parameter's description in the tool text ('URL completa do anúncio na OLX') adds minimal meaning beyond the schema's own description (which includes an example). Given the context signal of 0% schema coverage, this is adequate but not exceptional.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves complete details of a specific OLX listing from its URL. This explicitly differentiates it from sibling tools that perform searches or work with Mercado Livre.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage with a URL but does not explicitly guide when to use this tool versus alternatives like 'olx_buscar_anuncios' for searches. No exclusions or when-not-to-use are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clear, unique purpose, differentiated by marketplace (ml_ vs olx_) and action (buscar vs detalhe). No overlap.

Naming Consistency5/5

All tools follow a consistent snake_case pattern with marketplace prefix + verb + noun, all in Portuguese, making naming predictable.

Tool Count5/5

4 tools is well-scoped for covering two marketplaces with essential search and detail operations, fitting the common 3-15 range.

Completeness4/5

Covers core read operations for both marketplaces, but lacks write capabilities and some advanced filters (e.g., category list). Minor gaps.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for OLX marketplace. Enables AI assistants to search listings, get offer details, track prices over time, and compare offers across OLX Poland and other supported countries.
    622
    4
    MIT
  • F
    license
    Not graded
    quality
    B
    maintenance
    MCP server that provides access to Brazilian public and commercial data, including CNPJ company info, government procurement (PNCP) searches, and FIPE vehicle pricing, with optional alert registration for new tenders.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rodrigopg/mcp-brazil-marketplaces'

If you have feedback or need assistance with the MCP directory API, please join our Discord server