olx-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 chromiumCheck that it starts (it waits for an MCP client on stdin; stop with Ctrl+C):
uv run olx-mcpConnecting to a client
Claude Code
claude mcp add -s user olx -- uv run --directory /path/to/olx-mcp olx-mcpRestart 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-mcpTools
Tool | Purpose |
| Find |
| Which categories contain offers for a query, with counts. Use the |
| Category-specific filters and their allowed values (condition, brand, model, size…). |
| Turn an olx.pl listing URL into search parameters. |
| Search offers (parameters below). |
| Full details of one offer. |
| The offer's photos as images. |
olx_search parameters
Parameter | Type | Notes |
| string | Free text. |
| int | From |
| int | From |
| int | Radius around |
| number | PLN. |
|
| Default |
| int |
|
| object | Filters from |
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 |
| system | Path to the browser executable. |
|
| 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_photosby 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 neededProject 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 testsLicense
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search and browse global classifieds across 80 markets. No auth required for read-only access.
Car-listing search and used-car market analysis as agent tools.
Live kleinanzeigen.de search, ad, seller, category and location data for AI clients
Web data for agents. Extract web pages, crawl websites, discover URLs, and search the web.