# Avito MCP Server (Python 3.12+)

Кроссплатформенный Model Context Protocol (MCP) сервер на **Python 3.12+** для интеграции AI-ассистентов (Claude, Cursor, Antigravity, Gemini и др.) с платформой **Авито (Avito.ru)**.

Поддерживает **Linux (серверы / VPS)**, **Docker**, **macOS** и **Windows**.

Позволяет AI-агенту искать объявления, анализировать состояние товаров и продавцов, читать чаты и вести диалог / торговаться от имени вашего аккаунта.

---

## Возможности (Tools)

- `avito_create_item` — публикация новых объявлений с фото, категорией, параметрами и ценой
- `avito_search` — поиск по ключевым словам, городу, диапазону цен и сортировке (с превью-фотографиями)
- `avito_get_item_details` — получение полной карточки товара (галерея лота, описание, характеристики, статус бронирования, Авито Доставка, рейтинг продавца)
- `avito_send_message` — отправка сообщения продавцу в чат по объявлению (для торга или уточнения деталей)
- `avito_list_chats` — список недавних диалогов в мессенджере с превью и статусом непрочитанных
- `avito_get_chat_history` — чтение истории сообщений в конкретном чате

---

## Требования

- **Python** >= 3.12
- Установленный браузер: **Google Chrome**, **Microsoft Edge** или **Chromium** (на macOS и Windows находится автоматически; на Linux ищутся стандартные пути в `/usr/bin/` или задаются через переменную `AVITO_CHROME_PATH`)
- Либо **Docker** / **Docker Compose** (браузер и все зависимости уже встроены)

---

## Быстрый старт (Python 3.12+)

### 1. Клонирование и установка зависимостей

```bash
git clone https://github.com/foorsee/avito-mcp-server.git
cd avito-mcp-server

# Создание и активация виртуального окружения
python3 -m venv .venv
source .venv/bin/activate    # Linux / macOS
# или для Windows: .venv\Scripts\activate

# Установка зависимостей
pip install -r requirements.txt

# Установка браузера Chromium для Playwright
playwright install chromium
```

### 2. Разовая авторизация на Авито

Для того чтобы сервер мог писать продавцам и читать чаты от вашего имени:

- **macOS / Linux:**
  ```bash
  python login_avito.py
  # или ./login_avito.sh
  ```
- **Windows:**
  ```cmd
  python login_avito.py
  :: или login_avito.bat
  ```

Откроется окно браузера. Войдите в свой профиль на Авито по номеру телефона / СМС / пушу и нажмите `ENTER` в консоли. Сессия сохранится локально в папке `avito-data/storageState.json` (эта папка находится в `.gitignore` и никогда не попадает в репозиторий).

> **Для headless Linux серверов (без монитора):**  
> Авторизуйтесь на компьютере с дисплеем (Mac или Windows), а затем просто скопируйте созданную папку `avito-data` на сервер в корень проекта.

---

## 🐳 Развертывание в Docker (Production / VPS)

Сервер полностью готов к развертыванию в контейнере:

```bash
# 1. Поместите папку avito-data с авторизованной сессией в корень проекта
# 2. Сборка и фоновый запуск контейнера:
docker compose up --build -d

# Просмотр логов:
docker compose logs -f
```

Сессия, куки и профиль монтируются через том `./avito-data`, сохраняясь между перезапусками.

---

## Настройка MCP клиента

Добавьте сервер в конфигурационный файл вашего клиента (`mcp_config.json`, `claude_desktop_config.json` и др.):

### macOS / Linux
```json
{
  "mcpServers": {
    "avito": {
      "command": "/полный/путь/к/avito-mcp-server/.venv/bin/python",
      "args": [
        "/полный/путь/к/avito-mcp-server/avito_server.py"
      ]
    }
  }
}
```

### Windows
```json
{
  "mcpServers": {
    "avito": {
      "command": "C:/полный/путь/к/avito-mcp-server/.venv/Scripts/python.exe",
      "args": [
        "C:/полный/путь/к/avito-mcp-server/avito_server.py"
      ]
    }
  }
}
```

---

## Работа в Gemini Desktop и песочнице macOS (CDP Режим)

Если вы используете **Gemini Desktop** на macOS, приложение запускает MCP-серверы внутри защищенной песочницы (Seatbelt Sandbox), которая блокирует прямой запуск сторонних процессов через Mach Ports.

Сервер автоматически поддерживает подключение к Chrome через **Chrome DevTools Protocol (CDP)**:

1. **Разовый запуск в фоне:**
   ```bash
   python scripts/run_cdp.py
   ```

2. **Автозапуск через фоновый демон macOS (LaunchAgent):**
   Браузер будет автоматически запускаться при старте системы и висеть в фоне:
   ```bash
   python scripts/setup_daemon.py
   ```
   (Для отключения демона: `python scripts/uninstall_daemon.py`)

Сервер `avito_core.py` автоматически обнаружит запущенный на порту `9222` Chrome и подключится к нему.

### 3. Решение капчи / Разблокировка при «Проблеме с IP»

Если при частых запросах Авито показало капчу или слайдер-пазл:
```bash
python scripts/solve_captcha.py
```
Откроется окно браузера. Переместите слайдер (сложите пазл), скрипт автоматически определит прохождение капчи, обновит куки и перезапустит фоновый сервис.

---

## Переменные окружения (Опционально)

- `AVITO_DATA_DIR` — путь к директории хранения сессии (по умолчанию `./avito-data`).
- `AVITO_CHROME_PATH` (а также `CHROME_PATH`) — путь к конкретному исполняемому файлу Chrome / Chromium.
- `AVITO_HEADLESS` — принудительно включить (`true`) или выключить (`false`) headless-режим.
- `AVITO_CDP_URL` — адрес для подключения по CDP (по умолчанию `http://127.0.0.1:9222`).
- `AVITO_CDP_PORT` — порт отладки для Chrome CDP (по умолчанию `9222`).
- `AVITO_NO_SANDBOX` — принудительно включить `--no-sandbox` (на Linux под root или в Docker включается автоматически).

---

## Безопасность и приватность

- Все куки, токены авторизации и профиль сохраняются исключительно локально на вашем сервере/ПК в директории `avito-data/`.
- Папка `avito-data/` находится в `.gitignore` и никогда не попадает в репозиторий.
- Сервер использует естественные тайминги и реалистичные заголовки, предотвращая детекты автоматизации.

---

## Лицензия

MIT License.