Парсинг Xiaohongshu без боли с помощью XHS-Downloader

Китайская платформа Xiaohongshu (на западе ее знают как RedNote) уже несколько лет задает тренды в дизайне, моде и мобильной коммерции. Для аналитиков, маркетологов и специалистов по машинному обучению эта соцсеть представляет собой ценный источник визуальных данных. Попытка написать простой скрипт на requests или playwright для выгрузки постов быстро упирается в глухую оборону: строгая проверка TLS-отпечатков, динамические токены xsec_token, водяные знаки и защита медиафайлов.

Наткнувшись на репозиторий XHS-Downloader от JoeanAmier с более чем 12 тысячами звезд, я ожидал увидеть очередной скрипт на пару сотен строк. Оказалось, это полноценный комбайн для парсинга и выгрузки медиа, умеющий работать через консольный интерфейс, REST API, связку с браузером и даже через протокол MCP для AI-ассистентов.

Что внутри и почему оно работает

Xiaohongshu внимательно следит за тем, кто именно шлет запросы. Если заголовки можно подделать, то отпечаток TLS (JA3/JA4) при стандартных запросах из Python сразу выдает автоматизацию.

Автор проекта решил эту проблему технически грамотно:

curl_cffi вместо стандартного httpx или requests. Библиотека маскирует отпечаток TLS под реальный браузер (по умолчанию Chrome 146). Платформа считает запросы легитимными и не блокирует сессию по 403 ошибке.
FastAPI и Uvicorn отвечают за режим бэкенд-сервиса, генерируя готовую интерактивную документацию OpenAPI.
FastMCP реализует Model Context Protocol, превращая парсер в готовый инструмент для LLM.
Textual создает интерактивный псевдографический интерфейс (TUI) прямо в терминале.
aiosqlite асинхронно сохраняет метаданные публикаций и отслеживает историю загрузок.

Интерфейс программы 1

Интерфейс программы 2

Интерфейс программы 3

Четыре сценария работы

В зависимости от задач утилиту можно использовать в совершенно разных режимах.

1. Интерактивный TUI и командная строка

Если нужно скачать несколько постов вручную, запускается TUI-режим. Программа умеет отслеживать системный буфер обмена: вы копируете ссылку на публикацию в браузере, а утилита подхватывает ее и начинает скачивание в фоне.

Для пакетной обработки предусмотрен классический CLI:

python main.py --url "https://www.xiaohongshu.com/explore/ID1 https://www.xiaohongshu.com/explore/ID2" --download true

Если из длинной галереи картинок нужны конкретные слайды, параметр --index задает их порядковые номера (например, --index 1 3 5).

CLI режим 1

CLI режим 2

2. Браузерный скрипт через Tampermonkey

Для ручного ресерча автор написал юзерскрипт. Вы открываете сайт в браузере, а скрипт встраивает кнопки для сбора ссылок из поисковой выдачи, профилей авторов, закладок или лайков.

Установка юзерскрипта

Пользовательский скрипт 1

Пользовательский скрипт 2

Пользовательский скрипт 3

Пользовательский скрипт 4

Смена языка в скрипте

В конфиге можно включить опцию script_server = true. Тогда при нажатии кнопки в браузере скрипт автоматически перешлет задачу запущенному локально приложению, которое скачает файлы в нужную папку.

3. REST API для интеграции в свои сервисы

Команда python main.py api запускает веб-сервер на FastAPI. По адресу http://127.0.0.1:5556/docs открывается интерактивная документация Swagger.

Отправляем POST-запрос на эндпоинт /xhs/detail:

import httpx

response = httpx.post(
    "http://127.0.0.1:5556/xhs/detail",
    json={
        "url": "https://www.xiaohongshu.com/explore/64f...",
        "download": True,
        "check_record": True
    },
    timeout=10.0
)
print(response.json())

В ответе приходит полная информация о публикации: текст, теги, счетчики реакций, прямые ссылки на видео или изображения.

4. MCP-сервер для AI-агентов

Свежее и полезное дополнение — режим Model Context Protocol:

python main.py mcp

Сервер поднимает Streamable HTTP транспорт по адресу http://127.0.0.1:5556/mcp/.

Конфигурация MCP

Подключив этот эндпоинт к Claude Desktop или любому другому AI-ассистенту, вы наделяете модель инструментами для поиска, чтения метаданных и скачивания контента из Xiaohongshu прямо во время диалога.

MCP получение данных

MCP скачивание 1

MCP скачивание 2

Работа с медиа, Live Photos и дедупликацией

Утилита не просто дергает статичные картинки. Она умеет выкачивать так называемые Live Photos (живые фото), сохраняя как само изображение, так и короткое видео к нему.

Все скачанные идентификаторы постов попадают в базу SQLite (Volume/ExploreID.db). При повторном парсинге ленты или профиля загрузчик просто пропустит уже сохраненные записи, экономя трафик и дисковое пространство.

Конфигурационный файл Volume/settings.json позволяет гибко настроить логику сохранения:

Формат имени файла задается шаблоном: поддерживаются поля даты публикации, автора, заголовка, счетчиков лайков и ID.
Опция author_archive раскладывает посты по отдельным папкам авторов, обновляя название директории, если блогер сменил ник.
Флаг write_mtime меняет системную дату изменения файла на реальную дату публикации поста.
Метаданные можно сохранять параллельно в базу данных SQLite либо в отдельные .md и .txt файлы рядом с медиа.

Схема получения Cookie

Публичные посты скачиваются вообще без авторизации. Но если вам нужны видеоролики в максимальном разрешении и высоком битрейте, стоит передать параметр cookie (достаточно обычной веб-сессии гостя из DevTools браузера).

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

Проект написан на Python 3.12+. Для установки зависимостей проще всего использовать современный менеджер пакетов uv:

git clone https://github.com/JoeanAmier/XHS-Downloader.git
cd XHS-Downloader

# Установка зависимостей и запуск
uv sync --no-dev
uv run main.py

Любители контейнеризации могут запустить готовый образ:

docker run --name xhs-api -p 5556:5556 -v xhs_volume:/app/Volume -it joeanamier/xhs-downloader python main.py api

Если вы хотите использовать логику загрузчика внутри своего Python-приложения, есть удобный асинхронный контекстный менеджер:

import asyncio
from module import XHS

async def main():
    async with XHS(
        work_path="./downloads",
        image_format="JPEG",
        video_download=True,
        live_download=True
    ) as client:
        result = await client.extract(
            "https://www.xiaohongshu.com/explore/65d8a9f...",
            download=True
        )
        print("Скачано:", result.get("title"))

if __name__ == "__main__":
    asyncio.run(main())

DartNode

WeChat Pay Alipay

Кому проект пригодится

XHS-Downloader закрывает конкретную утилитарную нишу. Инструмент подойдет разработчикам, собирающим датасеты для обучения нейросетей, аналитикам китайского e-commerce рынка и командам, строящим контентные пайплайны.

Из шероховатостей можно отметить китайский язык большинства комментариев в репозитории, но в самом приложении интерфейс переведен на английский (language: "en_US"), а кодовая база написана чисто и структурированно. Если вам нужен надежный способ тянуть контент из Xiaohongshu без возни с селекторами и обходом блокировок — проект определенно стоит забрать в закладки.