# Turbo.az MCP Server

MCP (Model Context Protocol) server for Turbo.az automotive marketplace. This server enables Claude Desktop to search for cars and retrieve listing information from turbo.az.

## ⚠️ Important Note

Turbo.az blocks access from outside Azerbaijan. This server **must run from an Azerbaijani IP**:
- Local computer (in Azerbaijan)
- Via VPN with Azerbaijan IP
- From a VPS located in Azerbaijan

## 🚀 Installation

### 1. Requirements

- Python 3.10+
- Google Chrome browser
- pip

### 2. Server Setup

```bash
# Clone the repo or copy files
cd turbo-az-mcp

# Create virtual environment
python -m venv venv

# Activate
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install packages
pip install -e .
```

### 3. Test

```bash
# Run server manually
python -m src.server
```

### 4. Test MCP without LLM

Spawns the server and calls tools (requires Chrome):

```bash
uv run python scripts/test_mcp.py
```

## 🔧 Claude Desktop (local MCP, stdio)

**Local-only:** Claude Desktop runs the server as a subprocess. Do **not** use "Add custom connector" / Remote MCP URL.

1. Find and open the config file:
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. Add to `mcpServers` section (or copy `claude_desktop_config.example.json` from the project and change `cwd` to your path):

**With uv (recommended):**
```json
{
  "mcpServers": {
    "turbo-az": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.server"],
      "cwd": "/home/javid/dev/turbo-mcp"
    }
  }
}
```

**With Python / venv:**
```json
{
  "mcpServers": {
    "turbo-az": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/home/javid/dev/turbo-mcp"
    }
  }
}
```

**Note:** `cwd` is the full path to the project folder. Restart Claude Desktop.

### Claude on Windows, Server in WSL

If Claude Desktop is on Windows but the project is in WSL, use `wsl` in config. WSL non-interactive shell may not have `uv` in PATH, so use venv python:

```json
{
  "mcpServers": {
    "turbo-az": {
      "command": "wsl",
      "args": ["bash", "-c", "cd /home/javid/dev/turbo-mcp && .venv/bin/python -m src.server"]
    }
  }
}
```

Replace `/home/javid/dev/turbo-mcp` with your WSL project path. If venv is not `.venv` (e.g. `venv`), use `venv/bin/python` instead of `.venv/bin/python`.

**Chrome in WSL:** When server runs in WSL, Chrome/Chromium must be installed in WSL for Selenium (Windows Chrome won't work). In WSL terminal:
```bash
sudo apt update && sudo apt install -y chromium-browser
```
If `chromium-browser` requires snap, install Google Chrome for Linux or set `CHROME_BINARY=/usr/bin/chromium` (or installed path).

## 📋 Available Tools

### 1. `search_cars`
Search for cars.

**Parameters:**
- `make` - Brand (BMW, Mercedes, Toyota, etc.)
- `model` - Model (X5, E-Class, etc.)
- `price_min` / `price_max` - Price range (AZN)
- `year_min` / `year_max` - Year range
- `fuel_type` - Fuel: benzin, dizel, qaz, elektrik, hibrid
- `transmission` - avtomat, mexaniki
- `limit` - Number of results (default: 10)

**Example query:** "Search for BMW X5 from 2020, price up to 50000 AZN on Turbo.az"

### 2. `get_car_details`
Detailed listing information.

**Parameters:**
- `listing_id` - Listing ID or full URL

**Example query:** "Show details of this listing on Turbo.az: 12345678"

### 3. `get_makes_models`
List of makes and models.

**Parameters:**
- `make` - Brand (to see its models, empty = all makes)

**Example query:** "What BMW models are available on turbo.az?"

### 4. `get_trending`
New/popular listings.

**Parameters:**
- `category` - new, popular, vip
- `limit` - Number of results

## 🐛 Troubleshooting

### "403 Forbidden" error
- Make sure you're running from Azerbaijan IP
- Use VPN (Azerbaijan IP)

### ChromeDriver error
- Make sure Chrome browser is installed
- `webdriver-manager` automatically downloads ChromeDriver

### "DevToolsActivePort file doesn't exist" (WSL)
- `chromium-browser` (snap) often doesn't work in WSL. Install Google Chrome:
  ```bash
  wget -q https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
  sudo dpkg -i google-chrome-stable_current_amd64.deb
  sudo apt install -f
  ```
- Or with virtual display: `sudo apt install xvfb` then `xvfb-run -a uv run python scripts/test_mcp.py`

### Timeout error
- Check internet connection
- Check if turbo.az is working

## 📄 License

MIT