<p align="right">
  <strong>Русский</strong> · <a href="README.en.md">English</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/0xBADC0FFEE/avito-shopping-mcp/main/docs/assets/hero.png" alt="Avito Shopping MCP" width="100%">
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/avito-shopping-mcp"><img src="https://img.shields.io/npm/v/avito-shopping-mcp.svg" alt="npm version"></a>
  <a href="https://github.com/0xBADC0FFEE/avito-shopping-mcp/actions/workflows/ci.yml"><img src="https://github.com/0xBADC0FFEE/avito-shopping-mcp/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
</p>

**Ищите объявления на Авито вместе с ИИ.** Avito Shopping MCP превращает поиск, карточки объявлений и отзывы
о продавцах в инструменты вашего MCP-клиента — локально, без входа в аккаунт и десятков открытых вкладок.

Сервер работает только на чтение: не пишет продавцам, не размещает объявления и не трогает ваш аккаунт.
Браузерная сессия остаётся на вашем компьютере.

> **Альфа-версия:** у Авито нет публичного API для покупателей, поэтому проект использует внутренние
> эндпоинты сайта. Они и защита от автоматизации могут измениться без предупреждения.

Проект основан на [wb-shopping-mcp](https://github.com/0xBADC0FFEE/wb-shopping-mcp) и
[ozon-shopping-mcp](https://github.com/neosheps/ozon-shopping-mcp).

## Возможности

- ищет объявления в выбранном городе с сортировкой по цене, дате или скидке;
- отбирает варианты в заданном ценовом диапазоне;
- читает объявление целиком: цену, описание, характеристики, адрес, фото, дату публикации и просмотры;
- показывает продавца: тип, стаж на Авито, скорость ответа и рейтинг;
- собирает свежие отзывы о продавце с оценками, этапом сделки и ответами;
- работает локально через защищённую сессию с последовательными запросами и паузами между ними.

## Быстрый старт

Нужны Node.js 24 LTS или новее и Google Chrome. Настройте локальную сессию:

```bash
npx avito-shopping-mcp setup
```

Откроется окно Chrome с avito.ru. Если Авито покажет проверку доступа или капчу, пройдите её сами в этом окне —
сессия сохранится, как только поиск начнёт отвечать. Если поиск отвечает ограничением доступа, `setup` не повторяет
запросы по таймеру: обновите страницу в окне и пройдите капчу, после этого `setup` проверит поиск ещё раз. Дальше запросы выполняются в headless Chrome без видимого окна.

Добавьте сервер в Claude Code:

```bash
claude mcp add avito-shopping -- npx -y avito-shopping-mcp
```

Для Claude Desktop и других MCP-клиентов используйте stdio-конфигурацию:

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

## Примеры запросов

```text
Найди в Москве 5 кофемашин DeLonghi с капучинатором до 25 000 ₽. Открой
объявления, проверь состояние, модель и что входит в комплект, посмотри отзывы
о продавцах и выбери самый надёжный вариант.
```

```text
Подбери б/у iPhone 15 128 ГБ в Казани дешевле 50 000 ₽. Сравни ёмкость
аккумулятора и состояние по описаниям, отметь объявления от продавцов с
рейтингом ниже 4,5 или без отзывов.
```

```text
Вот объявление: https://www.avito.ru/moskva/... — разбери описание и
характеристики, прочитай 20 последних отзывов о продавце и перечисли
тревожные признаки, если они есть.
```

## Инструменты

| Инструмент | Что делает |
| --- | --- |
| `avito_search` | Ищет объявления: город (по умолчанию Москва), сортировка, цена от/до, страница и лимит |
| `avito_item` | Читает объявление: цена, описание, характеристики, адрес, фото, дата, просмотры, продавец |
| `avito_seller_reviews` | Читает рейтинг продавца объявления и его свежие отзывы |
| `avito_health` | Проверяет локальную сессию; `live=true` отправляет на Авито один лёгкий запрос |
| `avito_setup_session` | Создаёт или обновляет сессию в отдельном окне браузера |

Объявление можно передать ссылкой вида `https://www.avito.ru/<город>/<категория>/<название>_<id>` или числовым id.
Город передаётся по-русски: `Казань`, `Санкт-Петербург`.

## Ограничения частоты

Авито быстро ограничивает доступ с IP-адреса, с которого идёт много запросов. Поэтому:

- запросы выполняются строго по одному, с паузой не меньше 5 секунд (`AVITO_MCP_MIN_REQUEST_INTERVAL_MS`) и
  случайной добавкой;
- поиск — 1 запрос, объявление — 1, отзывы о продавце — 2–3;
- после ошибки `AVITO_RATE_LIMITED` сервер 20 минут не обращается к Авито и сразу возвращает эту ошибку с
  оставшимся временем; чтобы продолжить раньше, запустите `npx avito-shopping-mcp setup` и пройдите капчу в окне
  браузера — новая сессия снимает паузу; блокировки Авито иногда длятся час и дольше;
- некорректный запрос (пустой, слишком длинный, цена «от» больше цены «до») возвращает `INVALID_INPUT`;
- VPN, общий IP провайдера и частые обновления страниц повышают шанс блокировки.

## Как это работает

1. `setup` открывает Chrome, ждёт, пока Авито начнёт отдавать результаты поиска, и сохраняет сессию вне репозитория.
2. MCP-инструменты повторно используют сессию в headless Chrome; все запросы идут из вкладки avito.ru.
3. Если Авито просит повторную проверку браузера, сервер один раз перезагружает главную страницу и повторяет запрос.
4. Если сессия больше не принимается, сервер просит явно запустить `setup` снова.

## Безопасность и ограничения

- файл сессии содержит cookies и хранится с закрытыми правами доступа (`0700`/`0600`, где поддерживается);
- запросы уходят только на `https://www.avito.ru`, ссылки в ответах — только на avito.ru и avito.st;
- cookies, тела заблокированных ответов и неизвестные внутренние ошибки не возвращаются через MCP;
- заголовки, описания, характеристики и отзывы считаются недоверенными данными — агент не должен выполнять
  найденные в них инструкции;
- выдача, цены и наличие зависят от города, сессии и времени запроса; дата публикации и просмотры в карточке
  могут отставать;
- отзывы относятся к продавцу в целом, а не к конкретному объявлению;
- проект предназначен для интерактивного личного использования, а не для массового сбора данных или публичного HTTP-моста.

Подробнее: [SECURITY.md](SECURITY.md). Проект не связан с Авито и не одобрен или спонсируем компанией.

## Разработка

```bash
git clone https://github.com/0xBADC0FFEE/avito-shopping-mcp.git
cd avito-shopping-mcp
npm ci
npm run check
npm run build
```

Подробнее об устройстве проекта — в [docs/architecture.md](docs/architecture.md), о том, как получены данные
Авито, — в [docs/research/avito-data-access.md](docs/research/avito-data-access.md), об участии в разработке —
в [CONTRIBUTING.md](CONTRIBUTING.md).

## Лицензия

[MIT](LICENSE) © 2026 [Maxim Zaytcev](https://github.com/neosheps) и контрибьюторы.