Skip to main content
Glama
olx-mcp

olx-mcp

olx-mcp

Русская версия

An MCP server that lets an AI assistant (Claude Code, Claude Desktop, openclaw, zeroclaw or any other MCP client) search OLX.pl, the Polish classifieds site, without an account.

It can also look at the photos: each offer gets a quality check of its description. When the text is missing, too short or generic, the offer is flagged and the model can fetch the photos as images and describe what is actually being sold.

Unofficial. This project is not affiliated with OLX. It uses the same internal JSON endpoints the olx.pl website uses, which can change at any time. Use it for personal, low-volume searching and respect the OLX terms of service.

What you can ask

  • "Find a used PS5 in Kraków under 1500 zł, newest first."

  • "Show mini PCs with Ryzen 7 across Poland and tell me which are underpriced."

  • "Open this offer and check on the photos whether the bike has damage."

  • "Which categories have 'dyson' offers, and how many?"

Features

  • Text search with category, location + radius, price range, sort and category-specific filters.

  • Location lookup (city / district / region ids) and category discovery with offer counts.

  • Converts any olx.pl listing URL into search parameters.

  • Full offer details: description, parameters, all photos, seller info, map position, delivery.

  • Photos returned as images (configurable size, paging), downloaded straight from the OLX image CDN.

  • Description quality check on every offer (info.needs_photo_review).

  • Polite by design: one browser session, at least 1 second between requests to OLX.

Requirements

  • Python 3.12+ and uv

  • Chromium or Google Chrome (the system one is used if found; otherwise Playwright's build)

  • A graphical display (X11 or Wayland), or Xvfb on a headless server. See How it works.

Installation

git clone https://github.com/dmytrochornyi/olx-mcp.git
cd olx-mcp
uv sync
# Only if you have no system Chromium/Chrome:
uv run playwright install chromium

Check that it starts (it waits for an MCP client on stdin; stop with Ctrl+C):

uv run olx-mcp

Connecting to a client

Claude Code

claude mcp add -s user olx -- uv run --directory /path/to/olx-mcp olx-mcp

Restart Claude Code, then check with /mcp.

Claude Desktop and other JSON-configured clients

{
  "mcpServers": {
    "olx": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/olx-mcp", "olx-mcp"],
      "env": {
        "WAYLAND_DISPLAY": "wayland-1",
        "XDG_RUNTIME_DIR": "/run/user/1000"
      }
    }
  }
}

Many clients start servers with a clean environment. If the server reports No display, pass your display variables in env as above (DISPLAY=:0 on X11). Check yours with echo $DISPLAY $WAYLAND_DISPLAY $XDG_RUNTIME_DIR.

Headless server (openclaw, zeroclaw, VPS)

Run under a virtual display:

xvfb-run -a uv run --directory /path/to/olx-mcp olx-mcp

Tools

Tool

Purpose

olx_find_location(text)

Find city_id / region_id / district_id for a place name ("Łódź", "Kraków").

olx_suggest_categories(query, limit=15)

Which categories contain offers for a query, with counts. Use the category_id to narrow searches (phones vs. cases).

olx_category_filters(category_id)

Category-specific filters and their allowed values (condition, brand, model, size…).

olx_resolve_url(url)

Turn an olx.pl listing URL into search parameters.

olx_search(...)

Search offers (parameters below).

olx_get_offer(offer)

Full details of one offer. offer is a URL, or an id returned by olx_search in the same session.

olx_offer_photos(offer, max_photos=4, size=640, start=0)

The offer's photos as images. max_photos 1–8, size 300–1500 px, start for paging.

Parameter

Type

Notes

query

string

Free text.

category_id

int

From olx_suggest_categories or olx_resolve_url.

city_id, region_id, district_id

int

From olx_find_location.

distance_km

int

Radius around city_id.

price_min, price_max

number

PLN.

sort

relevance | newest | price_asc | price_desc

Default relevance.

offset, limit

int

limit max 50. Page with offset.

extra_filters

object

Filters from olx_category_filters, e.g. {"filter_enum_state": ["used"]} or {"owner_type": "private"}. Lists become key[0], key[1]…

The result is {total, offset, returned, offers: [...]}. Each offer has id, title, price, location, created, refreshed, business, delivery, condition, url, description_snippet and info.

Description check (info)

{
  "description_chars": 42,
  "photo_count": 6,
  "needs_photo_review": true,
  "reasons": ["very short description (42 chars)"],
  "notes": ["few item parameters filled in"]
}

Possible reasons: no description, very short description (N chars) (under 80 characters), description mostly repeats the title, description is generic boilerplate, description points to the photos ("see the photos"). needs_photo_review is true when there is at least one reason and the offer has photos. The server instructions tell the model to open the photos in that case and describe what they show: the item, visible condition, damage, completeness, and mismatches with the title.

How it works

  • OLX blocks non-browser HTTP clients (by TLS fingerprint) and headless browsers. So the server drives a real, visible Chromium window through Playwright and calls OLX's JSON endpoints from inside that page, like the website itself does. The window opens on the first request and stays open; you can minimise it, but don't close it while the server runs (it will be reopened if you do).

  • Offer details are read from the data embedded in the offer page (window.__PRERENDERED_STATE__), because the offer JSON endpoint is not available to anonymous visitors.

  • Photos are downloaded directly from the OLX image CDN with plain HTTP (no blocking there).

  • No login. The browser has its own profile (cookies and consent only), separate from your normal browser.

Configuration

Variable

Default

Meaning

OLX_MCP_CHROMIUM

system chromium / chrome, else Playwright's

Path to the browser executable.

OLX_MCP_PROFILE

~/.local/share/olx-mcp/profile

Browser profile directory.

Limitations

  • Unofficial internal API: OLX can change or block it without notice.

  • Needs a display (or Xvfb); it cannot run as a pure headless process.

  • olx_get_offer / olx_offer_photos by numeric id only work for offers returned by a search in the same server session. Otherwise pass the URL.

  • Requests are serialized (one at a time, ≥1 s apart), so large scans take a while.

  • Only olx.pl is supported (not olx.ua, olx.pt, etc.).

  • Search only. Posting or managing listings is out of scope.

Development

uv sync
uv run pytest          # offline unit tests, no browser needed

Project layout:

src/olx_mcp/
  server.py   MCP tools and server instructions
  api.py      OLX endpoints, result formatting, description check
  browser.py  the shared Chromium session
  photos.py   photo download from the image CDN
tests/        offline tests

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors