# OLX India MCP Server

An MCP (Model Context Protocol) server designed to searchclassified product listings and retrieve detailed specifications, images, and seller profiles from OLX India (`olx.in`).

This server allows AI assistants (like Claude, Cursor, etc.) to fetch real-time listings for cars, properties, mobiles, electronics, jobs, and services directly from OLX India.

## Features

- **Search Listings**: Find classified ads on OLX India with options to filter by query keywords, common Indian cities (Delhi, Mumbai, Bangalore, Pune, etc.), min/max price, sorting, and pagination.
- **Detailed Retrieval**: Extract full item specifications, seller info, posting date, specifications/parameters (e.g. brand, model, KM driven, fuel type), description, and image gallery.
- **Robust Scraping**: Employs curl-based request patterns to bypass JA3 TLS handshake blocks and load full page state objects.

---

## Tools

### 1. `search_listings`
Search for classified listings on OLX India.

**Input Arguments:**
- `query` (string, **required**): The product keywords to search for (e.g. `"iphone 15 pro"`, `"honda city"`).
- `location` (string, optional): Target city or state. Supports common terms: `"delhi"`, `"mumbai"`, `"bangalore"`, `"hyderabad"`, `"chennai"`, `"kolkata"`, `"pune"`, etc.
- `min_price` (number, optional): Minimum price filter in INR.
- `max_price` (number, optional): Maximum price filter in INR.
- `sort_by` (string, optional): Sort sorting. Enum: `price-asc`, `price-desc`, `newest`, `relevance`.
- `page` (number, optional): Page number to retrieve (starts at 1).

### 2. `get_listing_details`
Retrieve comprehensive details for a specific listing using its URL or ID.

**Input Arguments:**
- `url_or_id` (string, **required**): The full OLX listing URL or the numeric listing ID.

---

## Configuration & Usage

### 1. Using with Claude Desktop

Add the server to your Claude Desktop configuration file.

- **Windows path**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS path**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the following under the `mcpServers` section:

#### Option A: Running via npm (`npx`)
This is the recommended approach for quick execution.

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

#### Option B: Running from local cloned path
Use this if you have cloned the source code locally.

```json
{
  "mcpServers": {
    "olx-india-mcp": {
      "command": "node",
      "args": [
        "C:/path/to/olx-india-mcp/dist/index.js"
      ]
    }
  }
}
```
*(Make sure to use forward slashes `/` in paths on Windows in your JSON file).*

### 2. Using with Cursor
To configure with Cursor:
1. Open Cursor Settings -> Features -> MCP.
2. Click **+ Add New MCP Server**.
3. Name it `olx-india-mcp`.
4. Set the Type to `command`.
5. Enter the Command: `npx -y olx-india-mcp` (or `node C:/path/to/olx-india-mcp/dist/index.js` for local built path).

---

## Local Development

### Prerequisites
- [Node.js](https://nodejs.org/) (v18 or higher recommended)
- `curl` installed on your system (native on Windows 10/11, macOS, and most Linux distros)

### Setup & Build
1. Clone the repository.
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build the TypeScript source code:
   ```bash
   npm run build
   ```
4. Run locally (using stdio):
   ```bash
   npm start
   ```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.