olx-aluguel-mcp

An MCP server that lets Claude search rentals on OLX Brazil and flag likely rental scams before you send anyone money.

Why I built it

When I moved to Brazil I had to find an apartment in a city I didn't know, in a language I was still learning, on a marketplace where the golpe do aluguel (rental scam) is common. Every listing hid a different set of costs, and I couldn't tell a private owner from an agency, or a real ad from a fake one.

So I turned the checklist I was doing by hand into a tool.

Related MCP server: onehome-mcp

What it tells you about each listing

• Every cost: rent, condo fee, IPTU, the real monthly total, "gross" vs. "net" rent (punctuality discounts), fire insurance, FCI, bank fees, deposit (caução), seguro-fiança, contract fees, and which utilities are included.

• Owner or agency? With evidence: CRECI license, company name, commercial plan, ZAP feed.

• Contacts found in the text: phone numbers (including numbers spelled out in words), emails, links, Instagram, WhatsApp, and whether OLX verified the advertiser's phone.

• Address: neighborhood, CEP and the street it maps to (via ViaCEP), places mentioned in the description, and an approximate map link.

• Advertiser profile: account age, OLX identity/phone/email verification, reputation, advertiser's city, last activity.

• Scam risk score (0–100): price vs. the local market, brand-new account, advertiser in another state, typical scam phrases (pay before visiting, owner abroad, keys by mail, urgency, moving the chat off OLX), too few photos, and more. It also gives you questions to ask the advertiser and a safety checklist.

Tools

The location is the part of the OLX URL after /imoveis/aluguel/, for example:

• estado-pr/regiao-de-curitiba-e-paranagua → Curitiba and region

• estado-pr/regiao-de-curitiba-e-paranagua/boa-vista → Boa Vista district

• estado-pr/regiao-de-curitiba-e-paranagua/boa-vista/taruma → Tarumã neighborhood

Tip: filter on olx.com.br however you like and pass that URL to olx_buscar_alquileres in the url parameter.

How it works

• No official API, so it reads the same public pages you see in the browser. Requests go through curl_cffi (presenting as Chrome) with a 1.5 s delay between calls.

• Fallback to a real browser: if Cloudflare asks for verification, it switches to Playwright + Chromium automatically.

• The score is explainable, not a black box: every point comes from a named red or green flag, and the response lists them, so you can see why a listing looks risky.

• Tests against real saved pages: tests/fixtures holds an agency listing, a scam listing and a search page. When OLX changes its HTML, the tests break before the tool silently returns wrong data.

Quick install (Linux)

Register the run.sh launcher in Claude Desktop. On first run it installs its dependencies into .venv and logs to install.log:

{
  "mcpServers": {
    "olx-aluguel": {
      "command": "bash",
      "args": ["/PATH/TO/olx-aluguel-mcp/run.sh"]
    }
  }
}

Manual install

Requirements: Python 3.10+ and Claude Desktop.

1. Put the folder somewhere, e.g. C:\mcp\olx-aluguel-mcp (Windows) or ~/mcp/olx-aluguel-mcp (Linux/Mac).

2. Install it from that folder:

   python -m pip install -e .

   (Use python3 on Linux/Mac if needed. If your system requires a virtual environment: python -m venv .venv, then .venv\Scripts\pip install -e . on Windows or .venv/bin/pip install -e . on Linux/Mac.)

3. Check that it starts (it will wait for input; stop it with Ctrl+C):

   python -m olx_aluguel_mcp

4. In Claude Desktop go to Settings → Developer → Edit config and add the server to claude_desktop_config.json:

   Windows

   {
     "mcpServers": {
       "olx-aluguel": {
         "command": "C:\\mcp\\olx-aluguel-mcp\\.venv\\Scripts\\python.exe",
         "args": ["-m", "olx_aluguel_mcp"]
       }
     }
   }

   Linux / Mac

   {
     "mcpServers": {
       "olx-aluguel": {
         "command": "/PATH/TO/olx-aluguel-mcp/.venv/bin/python",
         "args": ["-m", "olx_aluguel_mcp"]
       }
     }
   }

   Without a virtual environment, use the path to your Python (where python on Windows, which python3 on Linux/Mac).

5. Restart Claude Desktop. The olx_* tools should appear in the tools menu.

If OLX blocks requests

Install the real-browser fallback:

python -m pip install playwright
python -m playwright install chromium

It kicks in automatically when a verification page appears. To always use it, add "env": {"OLX_USE_BROWSER": "1"} to the server config.

Example prompts

• "Find 1–2 bedroom apartments in Curitiba up to R$ 2,000, private owners only, and analyze the top 5."

• "Analyze this listing: https://pr.olx.com.br/regiao-de-curitiba-e-paranagua/imoveis/…"

• "Compare these 3 listings and tell me which one is cheapest per month with every fee included."

• "What does a 2-bedroom apartment cost on average in Tarumã?"

The tool's output is in Spanish, its author's first language.

Limitations and responsible use

• The scam score is a heuristic: it helps you prioritize and ask the right questions. It doesn't prove a listing is safe or fake. Never pay anything before visiting the property and checking the matrícula.

• The advertiser's full phone number is not extracted. OLX only shows it after clicking "Ver telefone", and this server respects that.

• OLX addresses are usually approximate (the CEP's street segment) unless the advertiser publishes the full address.

• It depends on OLX's HTML: if the site changes, parsers.py needs updating. Run python -m pytest tests to catch it.

• Personal use, low volume. OLX's Terms of Use restrict automated extraction. Don't use it to harvest data at scale or republish it.

License

MIT