magnit-mcp

Неофициальный MCP-сервер для покупок в «Магните» под собственной авторизацией: поиск продуктов, серверная корзина, доставка, сохранённые способы оплаты и заказ. Работает через stdio в Hermes и других MCP-клиентах. Python 3.11+, Linux или macOS. Лицензия MIT.

Каждый пользователь запускает свой процесс и импортирует свою сессию. Браузер, Playwright, отдельный сетевой сервис и российский jump host для запуска клиента не требуются. Доступ к API magnit.ru из вашей сети проверяется отдельно. Используется API сайта, поэтому совместимость зависит от изменений магазина.

Отправка заказов по умолчанию отключена. Флаг --enable-orders разрешает её, но каждый конкретный заказ всё равно требует запроса пользователя после показа состава, адреса, времени, карты и суммы. Создание заказа может запустить оплату.

Установка из исходников

git clone https://github.com/olegpelipenko/magnit-mcp.git
cd magnit-mcp
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/magnit-mcp --version
.venv/bin/python scripts/smoke_mcp.py --command .venv/bin/magnit-mcp

Последняя команда проверяет установленный MCP в отдельном пустом состоянии: без аккаунта, изменения корзины и покупки. Публикация в PyPI не требуется.

Для Hermes: передайте агенту docs/INSTALL_FOR_AGENT.md. Полная инструкция подключения: docs/HERMES.md.

Related MCP server: wegmans-mcp

Своя авторизация

Войдите в magnit.ru обычным браузером. Сохраните свой GET checkout/preview из DevTools → Network → Copy as cURL в закрытый файл вне репозитория. Как получить и обновлять экспорт: docs/AUTH.md.

.venv/bin/magnit-mcp import-session --input /private/path/magnit-cart.curl --dry-run
.venv/bin/magnit-mcp import-session --input /private/path/magnit-cart.curl
.venv/bin/magnit-mcp doctor --online

Импорт разбирает cURL как данные и не выполняет shell-команду. Нужен собственный экспорт текущей корзины с cookies и заголовками контекста магазина. При необходимости принимается также JSON с url и headers. Cookies, коды входа и содержимое экспорта не отправляются в чат или Git.

Подключение MCP

В настройках своего MCP-клиента укажите абсолютный путь к установленной команде:

{
  "mcpServers": {
    "magnit": {
      "command": "/absolute/path/to/magnit-mcp/.venv/bin/magnit-mcp",
      "args": ["--state-dir", "/private/path/magnit-state", "serve"]
    }
  }
}

Это общий формат клиентов с mcpServers. Hermes использует mcp_servers: см. пример YAML и инструкцию. Для оформления добавьте --enable-orders перед serve. Команда serve пишет в stdout только MCP-протокол, журналы — в stderr.

Инструменты

Порядок покупки

1. Проверить сессию. Выбрать сохранённый адрес до поиска: магазин доставки назначает Магнит. Код магазина из ссылки на товар для доставки не фиксируется.

2. Найти товары, прочитать корзину и изменить количество с её свежими revision и context_id. Количество абсолютное, а не прибавление.

3. Выбрать сохранённую карту и актуальное время из чекаута. Цены поиска предварительные; для согласования используется полный расчёт магазина.

4. Подготовить заказ, показать review и получить запрос пользователя на оформление.

5. Передать order_ref, точную сумму expected_total_kopecks, confirmed=true в magnit_create_order. Затем проверить статус заказа и оплаты.

Подробности для агента, недоступные товары и действия при ошибках: docs/USAGE.md. Скилл для базовой работы не нужен: MCP уже передаёт инструкции, схемы инструментов и результаты.

Состояние и ограничения

По умолчанию состояние хранится в $XDG_DATA_HOME/magnit-mcp или ~/.local/share/magnit-mcp; путь меняется через --state-dir, MAGNIT_MCP_STATE_DIR или TOML. .env не загружается. Каждому аккаунту нужен отдельный каталог. Права: каталог 0700, файлы 0600.

Локально хранятся авторизация, ссылки на выбранные адрес/оплату, кэш поиска и журнал отправки заказов. Корзина и недоступные позиции берутся с сервера Магнита. Отдельного локального списка покупок нет.

Обновление cookies не гарантирует бессрочный вход: если refresh отклонён, потребуется свежий экспорт. Реальное оформление проверено для одной доставки с сохранённой картой. Мультизаказы, отдельные ручные/возрастные сценарии и все разновидности весовых товаров не поддерживаются общим потоком. Проверенный весовой формат использует граммы: 1 кг бананов передаётся как 1000.

Неопределённый результат POST не повторяется: клиент сохраняет попытку до сети и блокирует повторную отправку до выяснения результата. Это локальная защита; серверная транзакционная идемпотентность не обещается. При is_paid=null магазин не дал явного признака списания, даже если заказ уже создан.

Разработка

.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q
.venv/bin/ruff check src tests scripts
.venv/bin/python scripts/smoke_mcp.py --command .venv/bin/magnit-mcp

Тесты используют искусственные ответы API и не делают покупок. CONTRIBUTING.md · Проверенные операции · Подготовка публикации · Приватность.