olx

The OLX MCP Server provides a programmable interface to search OLX across multiple domains (Portugal, Poland, Bulgaria, Romania, and Ukraine) and fetch detailed listing information. It supports searching with filters such as category, location, price range, and sorting, as well as retrieving comprehensive listing details including seller information. The server leverages browser automation (Playwright) to reliably scrape data, making it possible to query listings and extract metadata in a consistent format via your MCP client. You can issue search requests with domain, query, and optional filters, and you can request listing details by providing a listingId and domain. Typical usage involves defining an MCP command block in your client configuration, then querying for listings and, if needed, requesting details for a specific listing.

Prerequisites:

• Node.js (recommended) and npm installed on your machine
• Git (for from-source installation)
• Internet access to install packages

Option A: Claude Desktop Configuration (recommended for Claude users)

1. Install the MCP server in Claude Desktop by adding a new entry under mcpServers:

{
  "mcpServers": {
    "olx-mcp": {
      "command": "npx",
      "args": ["-y", "olx-mcp"]
    }
  }
}

2. Save changes and restart Claude Desktop to load the new configuration.

3. You can now reference the server as olx-mcp in your MCP client.

Option B: Global installation (npm)

1. Install the MCP package globally:

npm install -g olx-mcp

2. Use this configuration in your MCP client:

{
  "mcpServers": {
    "olx-mcp": {
      "command": "olx-mcp"
    }
  }
}

3. If you prefer to run via node directly after building from source, follow the development path below.

Option C: Development — From Source

1. Clone the repository and install dependencies:

git clone https://github.com/l-margiela/olx-mcp.git
cd olx-mcp
npm install
npm run build

2. Run the built server (example):

{
  "mcpServers": {
    "olx-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/olx-mcp/dist/index.js"]
    }
  }
}

3. This setup assumes you are building for development and testing purposes.

Prerequisites recap:

• Node.js and npm installed
• Git available for cloning
• Access to install npm packages globally if using the global installation path

Tips and common issues:

• Ensure your target OLX domains are supported: olx.pt, olx.pl, olx.bg, olx.ro, olx.ua.
• When using the MCP client, include domain, query, and optional filters (category, location, minPrice, maxPrice, maxPrice, sortBy).
• If you encounter authentication or rate-limit issues from OLX, consider adding slight delays between requests or using the browser automation mode (Playwright) to mimic real user interaction.
• For debugging MCP communication, you can use the MCP Inspector: npx @modelcontextprotocol/inspector node dist/index.js
• Check environment compatibility for Playwright (fonts, headless mode, and browser binaries).
• The npm package is olx-mcp; ensure you are referencing the correct command when running via MCP clients.