# olx-mcp-api

An MCP (Model Context Protocol) server for OLX classifieds, using the public JSON API that OLX itself uses — no browser automation, no HTML parsing, no authentication required.

Works with any OLX locale: **olx.pl**, olx.ro, olx.pt, olx.bg, olx.ua.

## Tools

| Tool | Endpoint | Description |
|------|----------|-------------|
| `search_offers` | `GET /api/v1/offers/` | Search by phrase, category, region/city/district + radius, price range, private/business seller, sorting, pagination (up to 50/page, ~1000 total) |
| `get_offer` | `GET /api/v1/offers/{id}/` | Full description, all photos, parameters, seller info |
| `resolve_olx_url` | `GET /api/v1/friendly-links/query-params/{path}/` | *Experimental.* Converts an OLX search URL (e.g. `/elektronika/krakow/`) into `category_id`, `city_id`, etc. |

Responses are trimmed to a compact format to reduce token usage.

## Quick Start (npx — no installation needed)

The easiest way to use this server is with `npx`. No cloning or building required.

### Claude Desktop

Edit the Claude Desktop config file for your OS:

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "olx": {
      "command": "npx",
      "args": ["-y", "github:explicite/olx-mcp-api"],
      "env": { "OLX_BASE_URL": "https://www.olx.pl" }
    }
  }
}
```

### Claude CLI

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "olx": {
      "command": "npx",
      "args": ["-y", "github:explicite/olx-mcp-api"],
      "env": { "OLX_BASE_URL": "https://www.olx.pl" }
    }
  }
}
```

Restart Claude Desktop / Claude CLI after saving.

## Manual Installation (from source)

```bash
git clone https://github.com/explicite/olx-mcp-api.git
cd olx-mcp-api
npm install
npm run build
npm test
```

Then use the local path in your config:

```json
{
  "mcpServers": {
    "olx": {
      "command": "node",
      "args": ["/absolute/path/to/olx-mcp-api/dist/index.js"],
      "env": { "OLX_BASE_URL": "https://www.olx.pl" }
    }
  }
}
```

**Windows path example:** `C:\\Users\\yourname\\src\\olx-mcp-api\\dist\\index.js`

## OLX_BASE_URL

Change the base URL to target a different OLX country:

| Value | Country |
|-------|---------|
| `https://www.olx.pl` | Poland (default) |
| `https://www.olx.ro` | Romania |
| `https://www.olx.pt` | Portugal |
| `https://www.olx.bg` | Bulgaria |
| `https://www.olx.ua` | Ukraine |

## Requirements

- Node.js 18 or later (for manual install)
- For `npx` usage: Node.js 18+ with npm

## Limitations

- Phone numbers (`/offers/{id}/limited-phones/`) require a logged-in session — not supported.
- `get_offer` takes a numeric `id` from search results, **not** the ID embedded in the HTML link (`...-IDxxxx.html`).
- This uses the unofficial frontend API. It may change without notice. The official [OLX Partner API](https://developer.olx.pl) is available but requires OAuth app registration and is intended for managing your own listings.

## License

MIT