Skip to main content
Glama
Sign In

OLX MCP

by ai.wondel
OverviewDiscussionsAdmin

Search OLX.pl classifieds

olx_search

Search offers on OLX.pl, Poland's largest classifieds site, across every category: flats and houses for rent or sale, cars and parts, phones and electronics, furniture, clothes, jobs, services, free items. Filter by words, category, place (city or district, with a radius) or voivodeship, price range, new/used, private vs business seller, and any category-specific attribute via filters. Common category_id values: Nieruchomości 3 (flats for rent 15, flats for sale 14, houses for rent 20, houses for sale 18, rooms 11, plots 709), Motoryzacja 5 (passenger cars 84, motorcycles 81, car parts 82), Elektronika 99 (smartphones 1839, laptops 1199, TVs 1849, game consoles 1604), Dom i Ogród 628 (furniture 565), Moda 87, Dla Dzieci 88, Sport i Hobby 767 (bicycles 461), Zwierzęta 103, Praca 4 (jobs), Usługi 4371, Oddam za darmo 1151 (free items). olx_categories lists the full tree and shows which categories a query's offers fall in. Pass an offer's id to olx_offer for the full description, all photos and map location. Fetched live from OLX.pl's public API (typically well under 1 s; a few seconds when it falls back to an unblocker). Result shape: { source, fetchedAt, query, resolved_location, total_count, offset, limit, next_offset, count, offers: [...], note? } — the list key is offers; total_count counts all matches, but OLX pages through only the first 1000 (pass next_offset as offset for more). Each offer: { id, url, title, price: { value, currency, negotiable, type, label, per?, previous_value? } | null, salary?, area_m2?, rooms?, params, city, district, region, category_id, category, seller_type, promoted, created_time, refreshed_time, photo, photos_count, description, external_url? }. price.value is a number in currency (PLN) or null when there is no amount. price.type: 'price' = the asking price (negotiable when the seller accepts offers; for flat/house rentals the monthly rent), 'arranged' (to be agreed) with value null, 'budget' = the advertiser's budget rather than an asking price, 'free' = giveaway with value 0, 'exchange' = swap with value null — so never read a missing amount as 0 PLN. per ('hour' | 'day' | 'night' | 'week' | 'month') marks a rate, e.g. equipment rented at 150 PLN per day — the value is then not a total. previous_value appears after a price drop. Jobs carry salary { from, to, currency, period, gross } instead of a price. params maps each attribute's key to its Polish display label (e.g. { state: 'Używane', m: '44,60 m²', rooms: '2 pokoje' }) — the keys are what filters use. description is a short excerpt; contact details are never included. An empty match answers count: 0 with a note saying why and what to change — a successful result, not an error.

Input Schema

NameRequiredDescriptionDefault
limitNoResults per call, 1–50. Default 20.
queryNoSearch words, matched loosely against titles and descriptions. Polish terms work best ('rower górski', 'kawalerka', 'iphone 13 pro'). Omit to browse a category/place.
offsetNoSkip this many results (0–1000; OLX pages through the first 1000 only). Default 0.
regionNoVoivodeship. Alone: search the whole voivodeship. With location: picks among same-name places.
filtersNoCategory-specific OLX filters (requires category_id). Keys come from an offer's `params` keys: 'filter_float_<key>:from' / ':to' for numbers, 'filter_enum_<key>' for choices (value or list of option keys). Examples — flats: { 'filter_float_m:from': 40, 'filter_float_m:to': 60, 'filter_enum_rooms': ['two', 'three'], 'filter_enum_furniture': 'yes' }; cars (84): { 'filter_float_year:from': 2018, 'filter_float_milage:to': 100000, 'filter_enum_petrol': 'diesel' }. OLX rejects a key the category does not have.
sort_byNo'relevance', 'newest' (most recently posted or refreshed first), 'price_asc' (cheapest first) or 'price_desc'. Default: OLX's own ordering.
locationNoPolish name of a city, town or village, optionally followed by a district: 'Kraków', 'Warszawa Mokotów', 'Gdańsk Wrzeszcz'. English names ('Warsaw') are not recognised; a partial name returns suggestions. Same-name villages: add region to choose.
no_cacheNoForce a fresh fetch and bypass this server's result cache (5 min). Default false.
price_toNoMaximum price in PLN (monthly rent for rentals).
conditionNoItem condition (Stan) — goods categories only (electronics, fashion, home…).
owner_typeNo'private' = private individuals only; 'business' = companies/agencies only.
price_fromNoMinimum price in PLN (monthly rent for rentals).
category_idNoOLX category id (see the list above or olx_categories), e.g. 15 = flats for rent.
distance_kmNoAlso include offers within this radius of location, in km (OLX offers 2, 5, 10, 15, 30, 50, 75, 100).
include_promotedNoAlso return OLX's paid top-ad slots (flagged promoted: true). They repeat across pages and ignore sort_by, so they are left out by default.

Output Schema

NameRequiredDescriptionDefault
noteNo
countYes
limitYes
queryYes
offersYes
offsetYes
sourceYes
fetchedAtYes
next_offsetNo
total_countNo
resolved_locationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses typical latency, unblocker fallback, the 1000-result paging limit, default exclusion of promoted ads, and that empty matches are successful results with a note. It also explains price-type semantics so missing values are never misread as 0 PLN.

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

Conciseness3/5

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

The description is front-loaded with purpose and category IDs, but then becomes a dense wall that duplicates output-shape and per-offer field documentation already covered by the output schema. Those details are behaviorally informative but make the description longer than necessary for tool selection and invocation.

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 15-parameter search tool with nested filters and an output schema, the description covers everything an agent needs: category taxonomy, filter construction, pagination behavior, price semantics, seller/condition constraints, and empty-result handling. Nothing critical is missing.

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 coverage is already 100%, so the baseline is 3, but the description adds useful meaning by listing common category_id values and explaining that filter keys derive from an offer's `params` keys. The filters schema itself contains examples, so the added value is real but partially overlapping.

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?

States a specific verb (search) and resource (OLX.pl classifieds) and enumerates supported categories and filters. It distinguishes itself from siblings by naming olx_categories for the taxonomy and olx_offer for full offer details.

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

Usage Guidelines5/5

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

Explicitly routes the agent: use olx_categories for the full tree and category distribution, and pass an offer's id to olx_offer for descriptions, photos, and map location. It also explains when to omit the query to browse a category/place and how to handle empty results as successful answers.

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

All OLX MCP toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources