mcp-brazil-marketplaces
This server provides MCP tools to search and retrieve public listings from Brazilian marketplaces OLX and Mercado Livre, with built-in anti-bot bypass mechanisms.
Search OLX ads (olx_buscar_anuncios): Filter by query, state (e.g., sp, rj), category (e.g., celulares, imoveis), price range (BRL), sort order (relevance, price, date), and pagination (up to 50 pages). Returns ads with title, price, location, date, image, and more.
Get OLX ad details (olx_detalhe_anuncio): Provide a URL to retrieve full description, seller info, location, images, category-specific attributes, and more.
Search Mercado Livre ads (ml_buscar_anuncios): Filter by query, price range (BRL), condition (novo/usado—heuristic), and state (heuristic). Pagination up to 20 pages. Returns ads with title, price, shipping info, attributes, URL, image.
Get Mercado Livre ad details (ml_detalhe_anuncio): Provide a URL to get description, images, seller, and other details.
Anti-bot bypass: Automatic User-Agent rotation, cookie warm-up, retry with exponential backoff, fallback via r.jina.ai for OLX (optional, controlled via env var OLX_JINA_FALLBACK), and Googlebot UA spoofing for Mercado Livre (can be overridden with ML_UA).
Unified schema: All results include fonte, id, titulo, preco, localizacao, data, url, imagem, plus source‑specific extras. fonte indicates origin (olx, olx_jina, or ml).
Configurable behavior: Adjust timeout, retries, concurrency, log level, and disable Jina fallback or Googlebot spoofing via environment variables.
Integration: Works with Claude Desktop, Claude Code, Cursor, and Continue via JSON config or plugin.
All tools are read‑only and idempotent.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-brazil-marketplacesBusque iPhones usados em São Paulo por até R$ 2000, ordenados por menor preço."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | shDepois rode direto:
uvx mcp-brazil-marketplacesOu via pip tradicional:
pip install mcp-brazil-marketplaces
mcp-brazil-marketplacesRelated 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.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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@rodrigopgClaude Code (CLI, sem plugin):
claude mcp add marketplaces-br -- uvx mcp-brazil-marketplacesCursor (~/.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 |
| string | Sim | Termo de busca |
| string | Não | Sigla do estado ( |
| string | Não | Slug de categoria ( |
| int | Não | Preço mínimo em reais |
| int | Não | Preço máximo em reais |
| string | Não |
|
| 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 |
| 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 |
| string | Sim | Termo de busca |
| int | Não | Preço mínimo em reais |
| int | Não | Preço máximo em reais |
| string | Não |
|
| string | Não | Sigla UF para filtragem pós-scraping (ver avisos) |
| 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 |
| string | Sim | URL completa do anúncio ( |
Diferenças entre as tools
Aspecto | OLX | Mercado Livre |
Páginas máx. | 50 | 20 |
Ordenação |
| Não suportada (ML não aceita via URL pública) |
Filtro | N/A | Heurística pós-scraping no título |
Filtro | Nativo na URL | Heurística pós-scraping (frequentemente vazio) |
Detalhe de anúncio |
|
|
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_marketplacesSchema 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 |
| string |
|
| int | string | ID do anúncio |
| string | Título |
| string | Preço formatado ( |
| string | null | Cidade/bairro/UF (pode ser null no ML) |
| string | null | Data legível (null no ML — não exposta nos cards) |
| string | URL canônica do anúncio |
| 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 |
| Scraping direto da OLX via httpx (caminho preferido) |
| Fallback: a OLX bloqueou e usamos r.jina.ai como proxy reader |
| 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 |
|
| 1.0–300.0 | Timeout HTTP em segundos |
|
| 0–20 | Tentativas no fetcher OLX (retry + troca de perfil) |
|
| 0.0–1.0 | Chance de warm-up da homepage antes do search |
|
|
| Desabilita fallback via |
|
|
| Nível do logger |
| (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. |
|
| 1–16 | Máx. de requests HTTP simultâneos |
|
| 0.0–30.0 | Gap mínimo em segundos entre requests ao mesmo host. |
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=1Com 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.1para contornar a página de challenge anti-bot. ML pode banir IPs que detectem o spoof; use moderadamente. Para desabilitar o spoof, definaMCP_BR_ML_USER_AGENTcom 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 --tagsO 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 toolsml_buscar_anunciosARead-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).
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_anuncioARead-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": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_anunciosARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_anuncioARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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
Each tool has a clear, unique purpose, differentiated by marketplace (ml_ vs olx_) and action (buscar vs detalhe). No overlap.
All tools follow a consistent snake_case pattern with marketplace prefix + verb + noun, all in Portuguese, making naming predictable.
4 tools is well-scoped for covering two marketplaces with essential search and detail operations, fitting the common 3-15 range.
Covers core read operations for both marketplaces, but lacks write capabilities and some advanced filters (e.g., category list). Minor gaps.
Maintenance
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
All HasData scraping tools in one MCP server: Google, TikTok, Instagram, maps, e-commerce and more.
MCP server for Brazilian Federal Senate open data (legislative, administrative, e-Cidadania).
Public MCP server for discovering open jobs. Search, filter, and get application links.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for Brazilian marketplace product search across Mercado Livre, Shopee, and AliExpress, with automatic x402 micropayments.471MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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.6224MIT
- AlicenseNot gradedqualityAmaintenanceMCP server for Brazilian data lookups (Pix codes, CEP, CNPJ) and web rendering tasks (Markdown, screenshots, PDFs) via a paid HTTP API with x402 billing.501MIT
- FlicenseNot gradedqualityBmaintenanceMCP 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
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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