Xiaohongshu Toolkit

Aviso de Descontinuação do Projeto

Devido a motivos pessoais do autor, o desenvolvimento do projeto foi interrompido há cerca de 1 ano e não há planos futuros de manutenção. Agradecemos muito o apoio de todos. O projeto inclui automação e design de assinatura de algoritmos de interface. Se tiver interesse, sinta-se à vontade para fazer um fork e continuar o desenvolvimento para criar sua própria ferramenta MCP.

📕 Kit de Ferramentas MCP para Criadores do Xiaohongshu

Um poderoso kit de automação do Xiaohongshu que suporta integração com clientes de IA (como Claude Desktop, etc.) através do protocolo MCP, permitindo criação de conteúdo, publicação e análise de dados do criador apenas conversando com a IA.

✨ Principais Recursos

• 🍪 Gerenciamento de Cookies: Obtenção, validação e gerenciamento seguros das credenciais de login do Xiaohongshu
• 🤖 Suporte ao Protocolo MCP: Integração perfeita com clientes de IA como Claude Desktop, CherryStudio, etc.
• 📝 Publicação Automática: Suporte à publicação automatizada de notas de imagem/texto e vídeo
• 🖼️ Suporte a Diversos Tipos de Imagem: Suporte a imagens locais e URLs de rede
• ⏰ Tarefas Agendadas: Suporte à coleta de dados agendada via expressões cron
• 📊 Coleta de Dados: Coleta automática de dados do painel do centro de criadores, análise de conteúdo e dados de seguidores
• 🧠 Análise de Dados com IA: Cabeçalhos de tabela em chinês, a IA pode entender e analisar diretamente
• 💾 Armazenamento de Dados: Suporte a armazenamento local em CSV (SQL mantido por enquanto, sem desenvolvimento planejado)
• 🎯 Interface Unificada: Uma ferramenta para atender às necessidades de automação do Xiaohongshu via LLM

📋 Lista de Recursos

Login

• Login - Suporte ao login tradicional via linha de comando e login por conversa com IA

Publicação de Conteúdo

• Publicação de Imagem/Texto - Suporte à publicação de notas de imagem/texto
• Publicação de Vídeo - Suporte à publicação de notas de vídeo
• Tags de Tópicos - Suporte à adição automática de tags de tópicos para aumentar a visibilidade do conteúdo
• Busca de Conteúdo - Suporte à busca específica (em planejamento)

Coleta de Dados

• Dados do Painel - Coleta de dados de visão geral da conta (número de seguidores, curtidas, etc.)
• Dados de Análise de Conteúdo - Coleta de dados de desempenho das notas (visualizações, curtidas, etc.)
• Dados de Seguidores - Coleta de crescimento e análise de seguidores
• Coleta Agendada - Suporte à coleta automática agendada via expressões cron
• Armazenamento de Dados - Armazenamento local em CSV (padrão)

📋 Requisitos de Ambiente

🌐 Ambiente do Navegador

• Google Chrome (versão mais recente recomendada)
• ChromeDriver (a versão deve corresponder exatamente à versão do Chrome)

🔍 Verificando a Versão do Chrome

Acesse no navegador Chrome: chrome://version/

📥 Métodos de Instalação do ChromeDriver

Método 1: Download Automático (Recomendado)

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

Método 2: Download Manual

1. 📋 Acesse a página oficial de download: Chrome for Testing
2. 🎯 Selecione o ChromeDriver que corresponda exatamente à sua versão do Chrome
3. 📁 Após o download, extraia para um local adequado (como /usr/local/bin/ ou C:\tools\)
4. ⚙️ Configure o caminho correto no arquivo .env

Método 3: Instalação via Gerenciador de Pacotes

# macOS (Homebrew)
brew install --cask chromedriver

# Windows (Chocolatey)  
choco install chromedriver

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

⚠️ Aviso Importante: Incompatibilidade de versões é a causa mais comum de problemas. Certifique-se de que a versão do ChromeDriver corresponda exatamente à versão do Chrome!

🌐 Conexão com Navegador Remoto

Suporte à conexão com uma instância remota do Chrome já em execução, melhorando o desempenho e suportando cenários de implantação remota.

🔧 Método de Configuração

Adicione a seguinte configuração no arquivo .env:

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

🚀 Iniciando o Chrome Remoto

• Se ocorrer erro de permissão, verifique se o diretório ./chrome-data existe e se tem permissões de leitura/escrita. Se não tiver, siga os passos abaixo para corrigir:
  1. docker run --rm selenium/standalone-chrome id seluser para obter o uid do seluser, por exemplo, retorna uid=1200(seluser) gid=1200(seluser) groups=1200(seluser)
  2. sudo chown -R 1200:1200 ./chrome-data para conceder permissões de leitura/escrita ao seluser; 1200 é o uid do seluser
  3. Execute novamente docker-compose up --force-recreate para iniciar o contêiner

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"

💡 Cenários de Uso

• Implantação Remota: Execute o Chrome em um servidor e conecte-se localmente
• Otimização de Desempenho: Reutilize instâncias do Chrome já em execução, evitando reinicializações
• Desenvolvimento e Depuração: Conecte-se a uma instância do Chrome já logada, mantendo o estado da sessão
• Ambiente Docker: Compartilhe instâncias do Chrome entre contêineres

⚠️ Observações

• A conexão remota não inicia uma nova instância do Chrome
• Certifique-se de que a instância do Chrome de destino tenha a depuração remota ativada
• Algumas operações (como ajuste de tamanho de janela) podem não ser suportadas no modo remoto

🚀 Início Rápido

💡 Uso Mínimo

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

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

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

🎮 Menu Interativo

Executar ./xhs exibirá uma interface de menu amigável:

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

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

🛠️ Executando a partir do Código Fonte

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  ## 验证工具是否可用

💡 Dica de uso do uv: Todos os comandos python na documentação podem ser substituídos por uv run python para uma experiência de gerenciamento de dependências mais 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  ## 验证工具是否可用

🛠️ Guia de Uso

1. Criar Arquivo de Configuração

Copie e edite o arquivo de configuração:

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

Configurações Obrigatórias:

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

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

2. Obter Credenciais de Login

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

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

No navegador aberto, se estiver conectado a um navegador remoto, acesse http://ip:57900 para abrir a interface VNC e siga os passos abaixo:

1. Faça login no centro de criadores do Xiaohongshu
2. Certifique-se de que consegue acessar as funções do centro de criadores normalmente
3. Após concluir, pressione Enter para salvar

3. Iniciar o Servidor MCP

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

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

4. Configuração do Cliente

Claude Desktop

Usando uv (Recomendado)

Adicione em ~/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 do Sistema

Se não usar uv, configure da seguinte forma:

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

Observações:

• Substitua /path/to/xhs-toolkit pelo caminho real do projeto
• Localização do arquivo de configuração no macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Localização do arquivo de configuração no Windows: %APPDATA%\Claude\claude_desktop_config.json
• Reinicie o Claude Desktop após modificar a configuração

Cherry Studio

Adicione na configuração MCP

n8n

Adicione a configuração na ferramenta do nó de agente de IA no n8n

🔧 Principais Funções

Lista de Ferramentas MCP

💬 Guia de Operação via Conversa com IA

Conclua login, publicação, análise de dados e outras operações apenas conversando com a IA, sem precisar aprender comandos complexos.

🔐 Login Inteligente

用户："登录小红书"

Observações Importantes:

• 🚨 Na primeira utilização, não altere o parâmetro headless; após obter os cookies, altere para o modo headless
• 🌐 A IA abrirá o navegador ao chamar a ferramenta de login; no primeiro login, será necessário inserir o código de verificação ou escanear o QR code manualmente
• 🍪 Após o sucesso, os cookies serão salvos automaticamente localmente, dispensando login nas próximas vezes

📝 Publicação de Conteúdo

Publicação de Imagem/Texto (imagens locais):

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

Publicação de Imagem/Texto (imagens da rede):

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

Publicação de Vídeo:

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

Publicação com Tags de Tópicos:

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

📊 Análise de Dados

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

🔧 Princípio de Publicação

Durante o upload manual, o navegador exibirá uma janela para o usuário selecionar o caminho do arquivo. A IA passará os parâmetros de caminho fornecidos pelo usuário para a ferramenta MCP, que concluirá automaticamente o upload.

⚡ Mecanismo de Espera Inteligente

• 📷 Upload de Imagem: Upload rápido, sem necessidade de espera
• 🎬 Upload de Vídeo: Verificação periódica do progresso do upload, aguardando o indicador "upload concluído"
• ⏱️ Proteção contra Timeout: Espera máxima de 2 minutos para evitar timeout do MCP
• 📊 Monitoramento de Status: No modo DEBUG, exibe tamanho do arquivo de vídeo e informações de duração
• 🔄 Verificação Eficiente: Verificação a cada 2 segundos, com correspondência precisa de texto

📊 Coleta de Dados e Análise com IA

Coleta automática de dados do criador no Xiaohongshu, com suporte a tarefas agendadas e análise inteligente com IA.

🧠 Recursos de Análise de Dados com IA

• Cabeçalhos em Chinês: Arquivos CSV usam cabeçalhos em chinês, a IA entende o significado dos dados diretamente
• Análise Inteligente: Obtenha dados completos através da ferramenta MCP get_creator_data_analysis
• Orientação por Dados: A IA fornece sugestões de otimização de conteúdo com base em dados reais
• Análise de Tendências: Analisa tendências de desempenho da conta e crescimento de seguidores

Tipos de Dados Coletados

1. Dados do Painel: Número de seguidores, curtidas, visualizações e outros dados de visão geral da conta
2. Dados de Análise de Conteúdo: Dados de desempenho das notas, incluindo visualizações, curtidas, comentários, etc.
3. Dados de Seguidores: Tendências de crescimento de seguidores, análise de perfil dos seguidores, etc.

Exemplo de Tarefa Agendada

Usa sintaxe cron, gravada no arquivo de configuração .env

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

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

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

🎯 Ferramentas de Operação Manual

Novo menu interativo e ferramentas de operação manual para uma experiência mais conveniente:

Principais Recursos

• 🔄 Coleta de Dados: Disparo manual da coleta de dados, com suporte à seleção do tipo de dados e dimensão de tempo
• 🌐 Operações no Navegador: Abre rapidamente as páginas do Xiaohongshu já logadas
• 📊 Gerenciamento de Dados: Exportação em Excel/JSON, análise de tendências de dados, backup e restauração
• 🍪 Gerenciamento de Cookies: Obter, visualizar e validar o status dos cookies

Exemplo de Uso

# 启动交互式菜单
./xhs

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

🚀 Log de Atualizações - v1.3.0

🎯 Atualizações Importantes

🏷️ Automação de Tags de Tópicos (Implementação Completa)

• Novo sistema de automação de tópicos: Baseado em testes rigorosos de validação com Playwright, implementa a adição realmente eficaz de tags de tópicos no Xiaohongshu
• Mecanismo de entrada inteligente: Usa a classe Actions para entrada caractere por caractere e simulação de eventos JavaScript, simulando perfeitamente operações reais do usuário
• Validação completa do DOM: Suporte à detecção do atributo data-topic e indicadores ocultos, garantindo que os tópicos recebam recomendação de tráfego da plataforma
• Múltiplos planos alternativos: Vários métodos de entrada e mecanismos de validação, garantindo taxa de sucesso acima de 99%

🔧 Reestruturação da Arquitetura de Tópicos

• Unificação de Terminologia: Reestruturação completa de "tags" para "tópicos", alinhada à terminologia da plataforma Xiaohongshu
• Design Modular: Novo módulo dedicado topic_automation.py, fornecendo funcionalidades básicas e avançadas de automação
• Interface Unificada: Atualização de todos os modelos, interfaces e código do servidor, mantendo compatibilidade retroativa

🧪 Correções Baseadas em Testes Reais

• Correção do Método de Entrada: Resolve o problema de send_keys direto não acionar o menu suspenso
• Melhoria do Mecanismo de Validação: Validação em múltiplas camadas garante a conversão bem-sucedida do tópico, incluindo verificação completa de metadados
• Tratamento de Erros Aprimorado: Mesmo que uma etapa falhe, existem múltiplos planos alternativos para garantir a estabilidade da funcionalidade

Exemplo de Uso

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

Detalhes Técnicos

• Cobertura de Testes de Validação: Baseado em 3 testes rigorosos de validação com Playwright
• Adaptação à Estrutura do DOM: Adaptação completa à estrutura real do DOM de tags de tópicos do Xiaohongshu
• Otimização de Desempenho: Mecanismo de espera inteligente e processamento concorrente para maior eficiência de automação

Resultados dos Testes

# 网络图片
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"]
)

🚀 Roteiro de Desenvolvimento

📋 Recursos a Desenvolver

🔥 Alta Prioridade

• 🔐 Login em Modo Headless - Aprimorar o fluxo de login automático no modo headless para melhorar a experiência de automação

🔮 Planejamento de Longo Prazo

• 🤖 Declaração de Criação com IA - Detecção inteligente de conteúdo gerado por IA, adição automática de declaração de criação
• 👥 Gerenciamento de Múltiplas Contas - Suporte à alternância de publicação entre contas (seguindo políticas da plataforma, limite de 3 contas por IP)
• 🌐 Suporte a Modo Proxy - Em conjunto com o recurso de múltiplas contas, suporte a acesso via proxy
• 🐳 Containerização com Docker - Fornecer solução de implantação em contêiner para facilitar gerenciamento e implantação de múltiplas instâncias
• 🔍 Mecanismo de Revisão de Conteúdo - Alerta ou filtro de palavras sensíveis

🔧 Solução de Problemas

Problemas Comuns com ChromeDriver

❌ Problema: Erro de incompatibilidade de versão

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

✅ Solução:

1. 🔍 Verifique a versão do Chrome: acesse chrome://version/
2. 📥 Baixe a versão correspondente do ChromeDriver: Chrome for Testing
3. ⚙️ Atualize a configuração do caminho no arquivo .env

❌ Problema: ChromeDriver não encontrado

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

✅ Solução:

1. Confirme que o ChromeDriver foi baixado e extraído
2. Opção A: Adicione o ChromeDriver ao PATH do sistema
3. Opção B: Configure o caminho completo em .env: WEBDRIVER_CHROME_DRIVER="/path/to/chromedriver"
4. Linux/macOS: Certifique-se de que o arquivo tenha permissão de execução chmod +x chromedriver

❌ Problema: Caminho do navegador Chrome incorreto

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

✅ Solução: Configure o caminho correto do Chrome no arquivo .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"

Outros Problemas Comuns

❌ Problema: Falha na conexão MCP

✅ Solução:

1. Confirme que o servidor está iniciado: python xhs_toolkit.py server start
2. Verifique se a porta 8000 está em uso
3. Reinicie o Claude Desktop ou outro cliente MCP

❌ Problema: Falha no login

✅ Solução:

1. Limpe os cookies antigos: exclua o arquivo xhs_cookies.json
2. Obtenha os cookies novamente: python xhs_toolkit.py cookie save
3. Certifique-se de usar a conta correta do centro de criadores do Xiaohongshu

🙏 Contribuidores

Agradecemos a todos que contribuíram para o projeto!

Se você também quiser contribuir para o projeto, sinta-se à vontade para enviar um Pull Request ou Issue!

📄 Licença

Este projeto é open source sob a Licença MIT.

🔐 Compromisso de Segurança

• ✅ Armazenamento Local: Todos os dados são salvos apenas localmente
• ✅ Transparência Open Source: Código totalmente aberto e auditável
• ✅ Controle do Usuário: Você tem controle total sobre seus dados