Xiaohongshu Toolkit

Aviso de suspensión del proyecto

Debido a razones personales del autor, el proyecto ha dejado de avanzar durante aproximadamente 1 año, y no se planea mantenerlo en el futuro. Muchas gracias por su apoyo. El proyecto incluye diseños de automatización y firma de algoritmos de interfaz. Si está interesado, puede hacer fork y continuar desarrollando su propio MCP tool.

📕 Xiaohongshu Toolkit

Un potente kit de herramientas de automatización para Xiaohongshu, compatible con la integración mediante el protocolo MCP con clientes de IA (como Claude Desktop, etc.), permitiendo crear contenido, publicar y analizar datos de creadores simplemente conversando con la IA.

✨ Características principales

• 🍪 Gestión de cookies: Obtener, verificar y gestionar de forma segura las credenciales de inicio de sesión de Xiaohongshu
• 🤖 Soporte del protocolo MCP: Integración perfecta con clientes de IA como Claude Desktop, CherryStudio, etc.
• 📝 Publicación automática: Admite publicación automatizada de notas con imágenes y videos
• 🖼️ Soporte de imágenes variadas: Admite imágenes locales y URLs de red
• ⏰ Tareas programadas: Admite recopilación de datos programada mediante expresiones cron
• 📊 Recopilación de datos: Recopila automáticamente datos del panel de creadores, análisis de contenido y datos de seguidores
• 🧠 Análisis de datos con IA: Encabezados de tabla en chino, la IA puede entender y analizar directamente
• 💾 Almacenamiento de datos: Admite almacenamiento local en CSV (SQL se mantiene por ahora, no se desarrollará)
• 🎯 Interfaz unificada: Una herramienta para satisfacer las necesidades de automatización de Xiaohongshu mediante LLM

📋 Lista de funciones

Inicio de sesión

• Inicio de sesión - Admite inicio de sesión tradicional por línea de comandos y mediante conversación con IA

Publicación de contenido

• Publicación de imágenes y texto - Admite publicación de notas con imágenes y texto
• Publicación de videos - Admite publicación de notas de video
• Etiquetas de temas - Admite agregar automáticamente etiquetas de temas para aumentar la exposición del contenido
• Búsqueda de contenido - Admite búsqueda específica (en plan de desarrollo)

Recopilación de datos

• Datos del panel - Recopila datos generales de la cuenta (seguidores, me gusta, etc.)
• Datos de análisis de contenido - Recopila datos de rendimiento de notas (vistas, me gusta, etc.)
• Datos de seguidores - Recopila crecimiento de seguidores y datos de análisis
• Recopilación programada - Admite recopilación automática programada mediante expresiones cron
• Almacenamiento de datos - Almacenamiento local en CSV (predeterminado)

📋 Requisitos del entorno

🌐 Entorno del navegador

• Google Chrome (se recomienda la última versión)
• ChromeDriver (la versión debe coincidir exactamente con la versión de Chrome)

🔍 Ver la versión de Chrome

Visite en el navegador Chrome: chrome://version/

📥 Métodos de instalación de ChromeDriver

Método 1: Descarga automática (recomendado)

# 使用webdriver-manager自动管理
pip install webdriver-manager

Método 2: Descarga manual

1. 📋 Visite la página oficial de descarga: Chrome for Testing
2. 🎯 Seleccione el ChromeDriver que coincida exactamente con su versión de Chrome
3. 📁 Descomprima después de la descarga en una ubicación adecuada (como /usr/local/bin/ o C:\tools\)
4. ⚙️ Configure la ruta correcta en el archivo .env

Método 3: Instalación mediante gestor de paquetes

# macOS (Homebrew)
brew install --cask chromedriver

# Windows (Chocolatey)  
choco install chromedriver

# Linux (Ubuntu/Debian)
sudo apt-get install chromium-chromedriver

⚠️ Aviso importante: La falta de coincidencia de versiones es la causa más común de problemas. ¡Asegúrese de que la versión de ChromeDriver coincida exactamente con la versión del navegador Chrome!

🌐 Conexión a navegador remoto

Admite conexión a una instancia remota de Chrome en ejecución, mejorando el rendimiento y admitiendo escenarios de implementación remota.

🔧 Método de configuración

Agregue la siguiente configuración en el archivo .env:

# 启用远程浏览器连接
ENABLE_REMOTE_BROWSER=true
REMOTE_BROWSER_HOST=http://xx.xx.xx.xx
REMOTE_BROWSER_PORT=xxxx

🚀 Iniciar Chrome remoto

• Si se reporta un error de permisos, verifique si el directorio ./chrome-data existe y si tiene permisos de lectura/escritura. Si no los tiene, siga los siguientes pasos para corregirlo:
  1. docker run --rm selenium/standalone-chrome id seluser para obtener el uid de seluser, por ejemplo, devuelve uid=1200(seluser) gid=1200(seluser) groups=1200(seluser)
  2. sudo chown -R 1200:1200 ./chrome-data para otorgar permisos de lectura/escritura a seluser; 1200 es el uid de seluser
  3. Ejecute nuevamente docker-compose up --force-recreate para iniciar el contenedor

version: '3.8'

services:
  selenium-chrome:
    image: selenium/standalone-chrome:latest
    container_name: selenium-chrome
    ports:
      - "54444:4444"
      - "57900:7900"
    shm_size: 2g
    environment:
      - SE_VNC_NO_PASSWORD=1
    volumes:
      - ./chrome-data:/home/seluser  # 更换挂载路径，确保权限
    restart: unless-stopped
    command: >
      bash -c "mkdir -p /home/seluser/.config/google-chrome &&
              touch /home/seluser/.config/google-chrome/test.txt &&
              /opt/bin/entry_point.sh"

💡 Escenarios de uso

• Implementación remota: Ejecutar Chrome en un servidor y conectarse localmente
• Optimización de rendimiento: Reutilizar instancias de Chrome en ejecución, evitando reinicios repetidos
• Depuración de desarrollo: Conectarse a una instancia de Chrome con sesión iniciada, manteniendo el estado de la sesión
• Entorno Docker: Compartir instancias de Chrome entre contenedores

⚠️ Notas

• La conexión remota no inicia una nueva instancia de Chrome
• Asegúrese de que la instancia de Chrome de destino tenga habilitada la depuración remota
• Algunas operaciones (como ajustar el tamaño de la ventana) pueden no ser compatibles en modo remoto

🚀 Inicio rápido

💡 Método de uso extremadamente simple

# 克隆项目
git clone https://github.com/aki66938/xhs-toolkit.git
cd xhs-toolkit

# 运行（会自动安装依赖）
./xhs              # Mac/Linux
xhs.bat            # Windows

# 或使用 Python
python install_deps.py  # 安装依赖向导
./xhs                   # 启动程序

🎮 Menú interactivo

Al ejecutar ./xhs se mostrará una interfaz de menú amigable:

╭─────────────────────────────────────────╮
│         小红书MCP工具包 v1.3.0           │
│           快速操作菜单系统                │
╰─────────────────────────────────────────╯

【主菜单】
1. 🔄 数据收集
2. 🌐 浏览器操作
3. 📊 数据管理
4. 🍪 Cookie管理
5. 🚀 MCP服务器
6. ⚙️  系统工具
0. 退出

🛠️ Ejecutar desde el código fuente

Método 1: uv (recomendado ⚡)

# 克隆项目
git clone https://github.com/aki66938/xhs-toolkit.git
cd xhs-toolkit

# 使用uv安装依赖并运行
uv sync
uv run python xhs_toolkit.py status  ## 验证工具是否可用

💡 Consejo de uso de uv: Todos los comandos python en la documentación se pueden reemplazar con uv run python para disfrutar de una experiencia de gestión de dependencias más rápida.

Método 2: pip (método tradicional)

# 克隆项目
git clone https://github.com/aki66938/xhs-toolkit.git
cd xhs-toolkit

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt
python xhs_toolkit.py status  ## 验证工具是否可用

🛠️ Guía de uso

1. Crear archivo de configuración

Copie y edite el archivo de configuración:

cp env_example .env
vim .env  # 编辑配置

Configuración requerida:

# Chrome浏览器路径
CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# ChromeDriver路径  
WEBDRIVER_CHROME_DRIVER="/opt/homebrew/bin/chromedriver"

2. Obtener credenciales de inicio de sesión

# 方式一：使用交互式菜单
./xhs
# 选择 4 -> Cookie管理 -> 1 -> 获取新的Cookies

# 方式二：直接命令
./xhs cookie save

En el navegador que se abre, si está conectado a un navegador remoto, puede visitar http://ip:57900 para acceder a la interfaz VNC y luego seguir los siguientes pasos:

1. Inicie sesión en el Centro de creadores de Xiaohongshu
2. Asegúrese de poder acceder normalmente a las funciones del Centro de creadores
3. Después de completar, presione Enter para guardar

3. Iniciar el servidor MCP

# 方式一：使用交互式菜单
./xhs
# 选择 5 -> MCP服务器 -> 1 -> 启动服务器

# 方式二：直接命令
./xhs server start

4. Configuración del cliente

Claude Desktop

Usando uv (recomendado)

Agregue en ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "xhs-toolkit": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/xhs-toolkit",
        "run",
        "python",
        "-m",
        "src.server.mcp_server",
        "--stdio"
      ]
    }
  }
}

Usando Python del sistema

Si no usa uv, puede configurar:

{
  "mcpServers": {
    "xhs-toolkit": {
      "command": "python3",
      "args": [
        "-m",
        "src.server.mcp_server",
        "--stdio"
      ],
      "cwd": "/path/to/xhs-toolkit",
      "env": {
        "PYTHONPATH": "/path/to/xhs-toolkit"
      }
    }
  }
}

Nota:

• Debe reemplazar /path/to/xhs-toolkit con la ruta real del proyecto
• Ubicación del archivo de configuración en macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Ubicación del archivo de configuración en Windows: %APPDATA%\Claude\claude_desktop_config.json
• Después de modificar la configuración, debe reiniciar Claude Desktop

Cherry Studio

Agregue en la configuración de MCP

n8n

Agregue la configuración en la herramienta del nodo de agente de IA en n8n

🔧 Funciones principales

Lista de herramientas MCP

💬 Guía de operación mediante conversación con IA

Puede completar inicio de sesión, publicación, análisis de datos, etc., simplemente conversando con la IA, sin necesidad de aprender comandos complejos.

🔐 Inicio de sesión inteligente

用户："登录小红书"

Avisos importantes:

• 🚨 En el primer uso, no cambie el parámetro headless. Después de obtener las cookies, cámbielo al modo sin cabeza (headless)
• 🌐 La IA abrirá el navegador al llamar a la herramienta de inicio de sesión. En el primer inicio de sesión, deberá ingresar manualmente el código de verificación o escanear el código QR
• 🍪 Después de tener éxito, las cookies se guardarán automáticamente localmente, y la próxima vez no necesitará iniciar sesión

📝 Publicación de contenido

Publicación de imágenes y texto (imágenes locales):

请发布一篇小红书笔记，标题："今日分享"，内容："..."，图片路径："/User/me/xhs/poster.png"

Publicación de imágenes y texto (imágenes de red):

请发布一篇小红书笔记，标题："美食分享"，内容："今天的美食"，使用这个网络图片：https://example.com/food.jpg

Publicación de videos:

请发布一篇小红书视频，标题："今日vlog"，内容："..."，视频路径："/User/me/xhs/video.mp4"

Publicación con etiquetas de temas:

请发布一篇小红书笔记，标题："AI学习心得"，内容："今天学习了机器学习基础"，话题："AI，人工智能，学习心得"，图片："/path/to/image.jpg"

📊 Análisis de datos

请分析我的小红书账号数据，给出内容优化建议

🔧 Principio de publicación

Durante la carga manual, el navegador mostrará una ventana emergente para que el usuario seleccione la ruta del archivo. La IA pasará los parámetros de ruta proporcionados por el usuario a la herramienta MCP, completando automáticamente la acción de carga.

⚡ Mecanismo de espera inteligente

• 📷 Carga de imágenes: Carga rápida, sin necesidad de esperar
• 🎬 Carga de videos: Detección por sondeo del progreso de carga, esperando que aparezca la marca "carga exitosa"
• ⏱️ Protección de tiempo de espera: Espera máxima de 2 minutos para evitar tiempos de espera en la llamada MCP
• 📊 Monitoreo de estado: En modo DEBUG, muestra el tamaño del archivo de video y la duración
• 🔄 Sondeo eficiente: Verificación cada 2 segundos, coincidencia precisa de texto

📊 Recopilación de datos y análisis con IA

Recopila automáticamente datos de creadores de Xiaohongshu, admite tareas programadas y análisis inteligente con IA.

🧠 Características del análisis de datos con IA

• Encabezados en chino: Los archivos CSV usan encabezados en chino, la IA puede entender el significado de los datos directamente
• Análisis inteligente: Obtenga datos completos mediante la herramienta MCP get_creator_data_analysis
• Basado en datos: La IA proporciona sugerencias de optimización de contenido basadas en datos reales
• Análisis de tendencias: Analiza tendencias de rendimiento de la cuenta y crecimiento de seguidores

Tipos de datos recopilados

1. Datos del panel: Seguidores, me gusta, vistas, etc., datos generales de la cuenta
2. Datos de análisis de contenido: Datos de rendimiento de notas, incluyendo vistas, me gusta, comentarios, etc.
3. Datos de seguidores: Tendencias de crecimiento de seguidores, análisis de perfil de seguidores, etc.

Ejemplo de tarea programada

Use sintaxis cron, escríbala en el archivo de configuración .env

# 每6小时采集一次
COLLECTION_SCHEDULE=0 */6 * * *

# 工作日上午9点采集
COLLECTION_SCHEDULE=0 9 * * 1-5

# 每月1号凌晨2点采集
COLLECTION_SCHEDULE=0 2 1 * *

🎯 Herramientas de operación manual

Nuevo menú interactivo y herramientas de operación manual para una experiencia más conveniente:

Funciones principales

• 🔄 Recopilación de datos: Activar manualmente la recopilación de datos, admite selección de tipo de datos y dimensión temporal
• 🌐 Operaciones del navegador: Abrir rápidamente las páginas de Xiaohongshu con sesión iniciada
• 📊 Gestión de datos: Exportar Excel/JSON, analizar tendencias de datos, respaldo y restauración
• 🍪 Gestión de cookies: Obtener, ver, verificar el estado de las cookies

Ejemplo de uso

# 启动交互式菜单
./xhs

# 或使用命令行
./xhs manual collect --type all      # 收集所有数据
./xhs manual browser --page publish  # 打开发布页面
./xhs manual export --format excel   # 导出Excel
./xhs manual analyze                 # 分析数据趋势

🚀 Registro de actualizaciones - v1.3.0

🎯 Actualizaciones importantes de funciones

🏷️ Sistema de automatización de etiquetas de temas (implementación completa)

• Nuevo sistema de automatización de temas: Basado en pruebas rigurosas de Playwright, implementa la adición efectiva de etiquetas de temas en Xiaohongshu
• Mecanismo de entrada inteligente: Usa la clase Actions para entrada carácter por carácter y simulación de eventos JavaScript, simulando perfectamente las operaciones reales del usuario
• Verificación completa del DOM: Admite detección del atributo data-topic e indicadores ocultos, asegurando que los temas reciban recomendación de tráfico de la plataforma
• Múltiples planes alternativos: Múltiples métodos de entrada y mecanismos de verificación, proporcionando una tasa de éxito superior al 99%

🔧 Refactorización y mejora de la arquitectura de temas

• Unificación de terminología: Refactorización completa de "etiquetas" a "temas", alineándose con la terminología de la plataforma Xiaohongshu
• Diseño modular: Nuevo módulo dedicado topic_automation.py, que proporciona funciones de automatización básicas y avanzadas
• Unificación de interfaces: Actualización de todos los modelos, interfaces y código del servidor, manteniendo compatibilidad hacia atrás

🧪 Correcciones clave basadas en pruebas reales

• Corrección del método de entrada: Resuelve el problema de que send_keys directo no activa el menú desplegable
• Mejora del mecanismo de verificación: Verificación en múltiples capas para asegurar la conversión exitosa de temas, incluyendo verificación completa de metadatos
• Mayor tolerancia a fallos: Incluso si un paso falla, hay múltiples planes alternativos para asegurar la estabilidad de la función

Ejemplo de uso

# 新的话题功能使用（MCP工具中自动支持）
smart_publish_note(
    title="AI学习心得",
    content="分享一些人工智能学习经验",
    topics=["AI", "人工智能", "学习心得"],  # 新增话题参数
    images=["image.jpg"]
)

Detalles técnicos

• Cobertura de pruebas de verificación: Basado en 3 pruebas rigurosas de Playwright
• Adaptación de la estructura DOM: Adaptación completa a la estructura DOM real de etiquetas de temas de Xiaohongshu
• Optimización de rendimiento: Mecanismo de espera inteligente y procesamiento concurrente para mejorar la eficiencia de automatización

Efecto de las pruebas

# 网络图片
smart_publish_note(
    title="美食分享",
    content="今天的美食",
    images=["https://example.com/food.jpg"]
)

# 混合使用
smart_publish_note(
    title="旅行记录",
    content="风景很美",
    images=["/local/photo.jpg", "https://example.com/view.jpg"]
)

🚀 Hoja de ruta de desarrollo

📋 Funciones pendientes

🔥 Alta prioridad

• 🔐 Inicio de sesión en modo sin cabeza - Completar el flujo de inicio de sesión automático en modo sin cabeza para mejorar la experiencia de automatización

🔮 Planificación a largo plazo

• 🤖 Declaración de creación con IA - Detección inteligente de contenido generado por IA, agregando automáticamente la marca de declaración de creación
• 👥 Gestión de múltiples cuentas - Admite cambio entre múltiples cuentas para publicar (siguiendo las políticas de la plataforma, límite de 3 cuentas por IP)
• 🌐 Soporte de modo proxy - En combinación con la función de múltiples cuentas, admite acceso a la red mediante proxy
• 🐳 Contenedorización con Docker - Proporcionar soluciones de implementación en contenedores para facilitar la gestión e implementación de múltiples instancias
• 🔍 Mecanismo de revisión de contenido - Aviso o filtrado de palabras sensibles

🔧 Solución de problemas

Problemas comunes de ChromeDriver

❌ Problema: Error de falta de coincidencia de versiones

selenium.common.exceptions.SessionNotCreatedException: session not created: This version of ChromeDriver only supports Chrome version XX

✅ Solución:

1. 🔍 Verifique la versión de Chrome: visite chrome://version/
2. 📥 Descargue la versión correspondiente de ChromeDriver: Chrome for Testing
3. ⚙️ Actualice la configuración de ruta en el archivo .env

❌ Problema: ChromeDriver no encontrado

selenium.common.exceptions.WebDriverException: 'chromedriver' executable needs to be in PATH

✅ Solución:

1. Confirme que ChromeDriver se ha descargado y descomprimido
2. Opción A: Agregue ChromeDriver al PATH del sistema
3. Opción B: Configure la ruta completa en .env: WEBDRIVER_CHROME_DRIVER="/path/to/chromedriver"
4. Linux/macOS: Asegúrese de que el archivo tenga permisos de ejecución chmod +x chromedriver

❌ Problema: Ruta incorrecta del navegador Chrome

selenium.common.exceptions.WebDriverException: unknown error: cannot find Chrome binary

✅ Solución: Configure la ruta correcta de Chrome en el archivo .env

# macOS
CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

# Windows
CHROME_PATH="C:\Program Files\Google\Chrome\Application\chrome.exe"

# Linux
CHROME_PATH="/usr/bin/google-chrome"

Otros problemas comunes

❌ Problema: Fallo de conexión MCP

✅ Solución:

1. Confirme que el servidor está iniciado: python xhs_toolkit.py server start
2. Verifique si el puerto 8000 está ocupado
3. Reinicie Claude Desktop u otros clientes MCP

❌ Problema: Fallo de inicio de sesión

✅ Solución:

1. Elimine las cookies antiguas: borre el archivo xhs_cookies.json
2. Vuelva a obtener las cookies: python xhs_toolkit.py cookie save
3. Asegúrese de usar la cuenta correcta del Centro de creadores de Xiaohongshu

🙏 Contribuyentes

¡Gracias a todos los que han contribuido al proyecto!

Si también desea contribuir al proyecto, ¡no dude en enviar un Pull Request o Issue!

📄 Licencia

Este proyecto está bajo la licencia MIT.

🔐 Compromiso de seguridad

• ✅ Almacenamiento local: Todos los datos se guardan solo localmente
• ✅ Código abierto y transparente: El código es completamente abierto y auditable
• ✅ Control del usuario: Usted tiene control total sobre sus datos