marketua

An MCP server that lets AI agents (Claude Desktop, Hermes Agent, Cursor, OpenCode, …) search Ukrainian marketplaces — OLX, Hotline.ua, Prom.ua and Rozetka — from a plain-language prompt and get back structured offers with links.

Status: alpha. OLX, Hotline and Prom work out of the box (no tokens); Rozetka is covered through the optional Bright Data MCP server (free tier: 5 000 requests/month). Verified with MCP Inspector and a real agent (OpenCode), including a 4-marketplace price comparison from a single prompt.

Idea

Ask in natural language:

"SSD 120–560 GB, 2.5", used, up to 1500 UAH"

and get a structured list of matching offers — title, price, location, link — instead of a wall of search results.

Why not just use web search?

For one-off lookups the difference is small; for structured comparison and monitoring it is the point.

How it works

natural-language prompt
        │
        ▼
  LLM (OpenCode / Hermes / Claude)  ── maps prompt → tool arguments
        │
        ▼
  MCP tools  ── search, filters, details, references
        │
        ▼
  Marketplace providers ── OLX (JSON API), Hotline / Prom (SSR), Rozetka (Bright Data MCP)
        │
        ▼
  structured offers (title, price, location, url)

Tools

The server exposes these MCP tools (OLX / Hotline / Prom — registered out of the box):

• search_offers(query, min_price, max_price, region_id, city_id, category_id, state, filters, limit, offset, include_promoted, sort) — one page of offers plus the total match count. Category-specific attributes go into filters as {"key": "value"} (choice) or {"key": [from, to]} (range). sort: newest (server-side), price_asc/price_desc (sorts the returned page). Promoted listings are excluded unless include_promoted=True.
• get_offer_details(offer_id) — full listing: plain-text description, characteristics, photo URLs, seller, status, dates.
• list_filters(query, category_id) — discovers which category-specific filters exist for a query (keys + sample values). Call before search_offers when an attribute is mentioned. category_id restricts the sample to one category (broad queries otherwise mix categories).
• list_categories() — curated category id/name list (static snapshot; OLX deprecated the live category endpoint).
• list_regions() — OLX region (oblast) and major city ids.
• hotline_search_offers(query, min_price, max_price, limit, offset) — Hotline product models (new items from shops) with the minimum shop price.
• prom_search_offers(query, min_price, max_price, limit, offset) — Prom products (new items from shops).

Rozetka has no tool in this server — it is queried through the Bright Data MCP browser tools (see Optional: Bright Data MCP). The server's instructions tell the agent to do so automatically for price comparisons.

Example prompts

Find me an SSD 120–560 GB, 2.5", used, up to 1500 UAH on OLX

Cheap used monitors in Kyiv up to 2000 UAH, show the 5 cheapest

Details of offer 931436822

The agent maps these onto the tools: it calls list_filters to learn valid filter keys, list_regions/list_categories for ids, then search_offers with the narrowed arguments. Server-side instructions tell it to report only filters actually used and to format the result as a list with prices and links.

Quick start

pip install marketua        # or: uvx marketua (no install needed)
marketua                    # runs the MCP server over stdio (a client spawns it)

For development from this repo:

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q     # tests

Connect an agent

Any MCP client works. OpenCode:

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "marketua": {
      "type": "local",
      "command": ["uvx", "marketua"],
      "enabled": true
    },
    // Rozetka (and any JS-rendered / Cloudflare-protected site) goes through
    // the Bright Data MCP — free tier: 5 000 requests/month. Token from
    // Bright Data → Settings → API Tokens (see .env.example in this repo).
    "brightdata": {
      "type": "remote",
      "url": "https://mcp.brightdata.com/mcp?token={env:BRIGHT_DATA_API_KEY}&tools=scrape_as_markdown,scrape_as_html,search_engine&groups=browser",
      "enabled": true
    }
  }
}

If the client can't find uvx: GUI apps (VS Code, Claude Desktop, Cursor) often don't inherit your shell's PATH, so a freshly installed uv (in ~/.local/bin) may be invisible to them. Find the path with which uvx and put it in command, or skip uvx entirely: pip install marketua and use marketua as the command.

Optional env vars. The server reads MARKETUA_DISABLE_PROVIDERS (comma-separated: olx, hotline, prom) from its own environment to disable marketplaces. Most MCP clients (Claude Desktop, Cursor — see below) forward a per-server env block from the config; OpenCode does not forward env to spawned local MCP servers, so for OpenCode export the variable in the shell before launching it.

Then ask e.g. "Find me a used monitor up to 2000 UAH". The model picks the right tool itself: marketua_* for OLX / Hotline / Prom (free), brightdata_* for Rozetka and other hard-to-reach sites.

Optional: Bright Data MCP (for Rozetka)

Rozetka is a Cloudflare-protected Angular SPA — it needs a real browser, so it goes through Bright Data's official MCP server. It is optional: without it the agent searches OLX / Hotline / Prom and says Rozetka was skipped; with it, price comparisons cover all four marketplaces.

• Free tier: 5 000 requests/month, no credit card. Token: Bright Data → Settings → API Tokens (not the proxy credential). The agent spends ~2–4 requests per search (navigate + snapshot + get_text).
• Data lives only in your chat — nothing is stored by us.

Claude Desktop (claude_desktop_config.json). The env block is optional — include it only to disable marketplaces (comma-separated: olx, hotline, prom):

{
  "mcpServers": {
    "marketua": {
      "command": "uvx",
      "args": ["marketua"],
      "env": {
        "MARKETUA_DISABLE_PROVIDERS": "prom"
      }
    },
    "brightdata": {
      "url": "https://mcp.brightdata.com/mcp?token=YOUR_TOKEN&tools=scrape_as_markdown,scrape_as_html,search_engine&groups=browser"
    }
  }
}

Cursor (~/.cursor/mcp.json) — same optional env block for disabling marketplaces:

{
  "mcpServers": {
    "marketua": {
      "command": "uvx",
      "args": ["marketua"],
      "env": {
        "MARKETUA_DISABLE_PROVIDERS": "prom"
      }
    },
    "brightdata": {
      "url": "https://mcp.brightdata.com/mcp?token=YOUR_TOKEN&tools=scrape_as_markdown,scrape_as_html,search_engine&groups=browser"
    }
  }
}

For manual verification of every tool, use MCP Inspector:

npx @modelcontextprotocol/inspector --web uvx marketua

Platforms

Architecture

One stable interface, many providers:

MCP layer (tools)  →  Provider interface  →  [OLXProvider, HotlineProvider, PromProvider]
                                         (Rozetka — via the Bright Data MCP, no provider)

• MCP transport: stdio (simplest, the client spawns it as a child process). No hosted server — shipped as a Python package (pip install marketua / uvx marketua), so each user runs their own local instance.
• Provider interface keeps marketplace specifics behind one abstraction, so adding a platform never touches the agent-facing layer.
• OLX category ids are a static snapshot (the live category endpoint is deprecated); the server detects stale ids at query time and warns instead of silently returning wrong results.
• Credentials (e.g. the Bright Data token) are configured by you in your client or shell, never committed.

License & disclaimer

MIT. This project is educational. It uses only public, unauthenticated data and respects robots.txt and rate limits. Marketplace ToS may restrict automated access — use responsibly, keep request rates low, and do not redistribute data at scale or bypass any access controls. The optional Bright Data MCP is a third-party service with its own ToS and free-tier limits.