# 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
