pik-mcp

An MCP server that exposes the OLX.ba marketplace API (base URL https://api.olx.ba, documentation) as tools an LLM client can call: authenticate, browse and manage listings, read categories/attributes/locations, and run sponsorship/discount actions.

Setup

npm install
npm run build

Copy .env.example to .env and fill in your OLX credentials:

OLX_USERNAME=your-username-or-email
OLX_PASSWORD=your-password
OLX_DEVICE_NAME=pik-mcp          # optional
OLX_BASE_URL=https://api.olx.ba  # optional

The server logs in with these credentials on the first tool call, caches the bearer token in memory, and automatically re-authenticates if the token expires (HTTP 401). Credentials are never written to stdout (the MCP transport); logs go to stderr.

Running

pik-mcp speaks MCP over stdio. Point any MCP client at node dist/index.js.

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "olx": {
      "command": "node",
      "args": ["C:/Users/dkasi/Documents/Projects/pik-mcp/dist/index.js"],
      "env": {
        "OLX_USERNAME": "your-username-or-email",
        "OLX_PASSWORD": "your-password"
      }
    }
  }
}

Inspect / debug

npm run inspect   # opens @modelcontextprotocol/inspector against the server

Tools

Group	Tools
Auth	whoami, login_status
Listings (read)	search_listings, get_listing, get_user_listings
Categories	list_categories, get_category_children, get_category, get_category_attributes, get_category_brands, get_category_models, suggest_category, find_category
Locations	list_countries, list_cities, get_city, list_country_states, get_canton_cities
Listings (write)	create_listing, update_listing, publish_listing, refresh_listing, get_refresh_limits, get_listing_limits, finish_listing, hide_listing, unhide_listing, delete_listing
Images	upload_listing_image, delete_listing_image, set_main_listing_image
Sponsored / discount	get_sponsor_price, sponsor_listing, set_listing_discount, finish_listing_discount

Destructive tools (delete_listing, finish_listing, image delete) and paid tools (sponsor_listing, set_listing_discount) are flagged via MCP annotations and their descriptions. refresh_listing may consume a paid refresh once the free quota is exhausted — check get_refresh_limits first.

Searching listings

search_listings performs full-text search over OLX (GET /search). It is public and works without credentials, so you can browse even before setting up login. It accepts typed filters — q, category_id, brand_id, city_id, price_from/price_to, state (condition id, e.g. 2 = used), created_gte (e.g. "-24 hours"), per_page, page, sort_by/sort_order — plus an extra_params object passed through verbatim for advanced keys such as attribute filters (attr, attr_encoded).

By default it returns a compact summary per listing (id, title, price, category/brand/city ids, condition, date, cover image, and a https://olx.ba/artikal/{id} URL) alongside pagination meta and category aggregations. Pass raw: true to get the full untrimmed API payload.

Typical create-and-publish flow

1. suggest_category / find_category → pick a category_id
2. get_category_attributes → see required attributes; get_category_brands / get_category_models if applicable
3. get_city (or list_cities) → pick a city_id
4. create_listing → returns a DRAFT listing id
5. upload_listing_image → attach photos; set_main_listing_image for the cover
6. publish_listing → makes it visible in search

Notes / limitations

• The documented API exposes no generic "search all listings" endpoint. Browsing is done via categories + a user's listings (get_user_listings).
• Some success messages from OLX are in Bosnian (e.g. "Oglas je uspjesno objavljen") and are passed through as-is.

Project layout

src/
  index.ts          entry point (stdio transport)
  server.ts         builds McpServer, registers all tool groups
  config.ts         env-based configuration
  olx/
    client.ts       HTTP client: auth, token cache, 401 retry, error mapping
    types.ts        response shapes
  tools/            one file per resource group
  util/             shared zod schemas + result formatting