Xiaohongshu Toolkit

因作者个人原因项目已经停止推进约1年之久，后续也不再计划维护。 非常感谢大家支持，项目做了自动化及接口算法签名上的一些设计，有兴趣的朋友可以自行fork后继续二开构建属于自己的MCP工具

一个强大的小红书自动化工具包，支持通过MCP协议与AI客户端（如Claude Desktop等）集成，实现与AI对话即可进行内容创作、发布及创作者数据分析。

- 图文发布- 支持发布图文笔记
- 视频发布- 支持发布视频笔记
- 话题标签- 支持自动添加话题标签，提升内容曝光度
- 内容搜索- 支持指定搜索（开发计划中）

- 仪表板数据- 采集账号概览数据（粉丝数、获赞数等）
- 内容分析数据- 采集笔记表现数据（浏览量、点赞数等）
- 粉丝数据- 采集粉丝增长和分析数据
- 定时采集- 支持cron表达式的自动定时采集
- 数据存储- CSV本地存储（默认）

- Google Chrome 浏览器(最新版本推荐)
- ChromeDriver(版本必须与Chrome版本完全匹配)

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

- 📋 访问官方下载页面：Chrome for Testing
- 🎯 选择与您Chrome版本完全匹配的ChromeDriver
- 📁 下载后解压到合适位置（如/usr/local/bin/或C:\tools\）
- ⚙️ 在.env文件中配置正确路径

# macOS (Homebrew) brew install --cask chromedriver # Windows (Chocolatey) choco install chromedriver # Linux (Ubuntu/Debian) sudo apt-get install chromium-chromedriver

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

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"

# 克隆项目 git clone https://github.com/aki66938/xhs-toolkit.git cd xhs-toolkit # 运行（会自动安装依赖） ./xhs # Mac/Linux xhs.bat # Windows # 或使用 Python python install_deps.py # 安装依赖向导 ./xhs # 启动程序

# 克隆项目 git clone https://github.com/aki66938/xhs-toolkit.git cd xhs-toolkit # 使用uv安装依赖并运行 uv sync uv run python xhs_toolkit.py status ## 验证工具是否可用

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

# Chrome浏览器路径 CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" # ChromeDriver路径 WEBDRIVER_CHROME_DRIVER="/opt/homebrew/bin/chromedriver"

在弹出的浏览器中, 如果是连接的远程浏览器，可以访问http://ip:57900访问vnc界面，然后执行下面的步骤：

# 方式一：使用交互式菜单 ./xhs # 选择 5 -> MCP服务器 -> 1 -> 启动服务器 # 方式二：直接命令 ./xhs server start

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

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

- 需要将/path/to/xhs-toolkit替换为实际的项目路径
- macOS 用户配置文件位置：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows 用户配置文件位置：%APPDATA%\Claude\claude_desktop_config.json
- 修改配置后需要重启 Claude Desktop

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

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

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

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

手工上传过程中，浏览器会弹窗让用户选中文件路径，AI会将用户提供的路径参数传递给MCP工具，自动完成上传动作。

- 📷 图片上传：快速上传，无需等待
- 🎬 视频上传：轮询检测上传进度，等待"上传成功"标识出现
- ⏱️ 超时保护：最长等待2分钟，避免MCP调用超时
- 📊 状态监控：DEBUG模式显示视频文件大小和时长信息
- 🔄 高效轮询：每2秒检查一次，精确文本匹配

- 中文表头: CSV文件使用中文表头，AI可直接理解数据含义
- 智能分析: 通过get_creator_data_analysisMCP工具获取完整数据
- 数据驱动: AI基于真实数据提供内容优化建议
- 趋势分析: 分析账号表现趋势和粉丝增长情况
- 仪表板数据: 粉丝数、获赞数、浏览量等账号概览数据
- 内容分析数据: 笔记表现数据，包括浏览量、点赞数、评论数等
- 粉丝数据: 粉丝增长趋势、粉丝画像分析等

# 每6小时采集一次 COLLECTION_SCHEDULE=0 /6    # 工作日上午9点采集 COLLECTION_SCHEDULE=0 9   1-5 # 每月1号凌晨2点采集 COLLECTION_SCHEDULE=0 2 1  

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

- 全新话题自动化系统：基于严谨的Playwright验证测试，实现真正有效的小红书话题标签添加
- 智能输入机制：使用Actions类逐字符输入和JavaScript事件模拟，完美模拟真实用户操作
- 完整DOM验证：支持检测data-topic属性和隐藏标识，确保话题获得平台流量推荐
- 多重备用方案：多种输入方式和验证机制，提供99%+的成功率保障

- 术语统一：全面从"标签"重构为"话题"，符合小红书平台术语
- 组件化设计：新增topic_automation.py专用模块，提供基础和高级自动化功能
- 接口统一：更新所有模型、接口和服务器代码，保持向后兼容性

- 输入方式修复：解决直接send_keys无法触发下拉菜单的问题
- 验证机制改进：多层验证确保话题转换成功，包含完整的元数据检查
- 容错处理增强：即使某个环节失败也有多个备用方案，确保功能稳定性

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

- 验证测试覆盖率：基于3次严谨的Playwright验证测试
- DOM结构适配：完全适配小红书真实的话题标签DOM结构
- 性能优化：智能等待机制和并发处理，提升自动化效率

- 统一入口./xhs，无需记忆复杂命令
- 数字选择菜单，操作更直观
- 实时状态显示，了解系统状态
- 支持Windows（xhs.bat）和Unix系统

- manual collect: 手动数据收集，支持选择类型和维度
- manual browser: 打开已登录浏览器，快速访问各页面
- manual export: 导出数据为Excel或JSON格式
- manual analyze: 分析数据趋势，查看最佳笔记
- manual backup/restore: 数据备份和恢复功能

- 智能检测uv/pip环境
- 自动选择最佳Python环境
- 新增install_deps.py安装向导
- 同时支持uv和pip安装方式

- 简化启动命令，统一使用./xhs
- 改进Windows支持，提供bat和PowerShell脚本
- 优化代码结构，拆分模块避免单文件过大
- 增强错误处理和用户提示

- 支持 HTTP/HTTPS 图片链接直接发布
- 自动下载网络图片到本地临时目录
- 支持常见图片格式（jpg、png、gif、webp）

- 新增ImageProcessor模块统一处理各种图片输入
- 支持混合输入：["local.jpg", "https://example.com/img.jpg"]
- 更灵活的输入格式支持

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

- 修复无头模式失效问题：增强Chrome无头模式配置，添加多重保险参数
- 优化浏览器启动逻辑：使用--headless=new和--headless双重无头模式配置
- 优化配置验证：确保所有模块都使用统一的HEADLESS配置，避免配置不一致问题

- 添加了--disable-gpu-compositing、--disable-notifications等多个Chrome参数
- 改进了MCP服务器启动时的异步初始化逻辑
- 增强了Windows环境下的兼容性和稳定性

- 新增智能文件路径识别功能，支持多种输入格式自动解析
- 新增smart_parse_file_paths()函数，使用JSON解析、ast.literal_eval等多种解析方式
- 适配LLM对话场景和dify等平台的数组数据传递

- 逗号分隔："a.jpg,b.jpg,c.jpg"
- 数组字符串："[a.jpg,b.jpg,c.jpg]"
- JSON数组：'["a.jpg","b.jpg","c.jpg"]'
- 真实数组：["a.jpg", "b.jpg", "c.jpg"]
- 混合格式："[a.jpg,'b.jpg',\"c.jpg\"]"

- 解决用户反馈的多张图片上传格式识别问题
- 智能区分字符串和数组格式，避免数据类型判断错误
- 支持从不同平台（dify、LLM对话等）传递的各种数据格式
- 增强容错能力，即使格式不标准也能尽量解析

- 🤖 AI创作声明- 智能检测AI生成内容，自动添加创作声明标识
- 👥 多账号管理- 支持多账号切换发布（遵循平台政策，单IP限制3个账号）
- 🌐 代理模式支持- 配合多账号功能，支持代理网络访问
- 🐳 Docker容器化- 提供容器化部署方案，便于多实例管理和部署
- ​🔍 内容审核机制- 敏感词提醒或过滤

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

- 🔍 检查Chrome版本：访问chrome://version/
- 📥 下载对应版本的ChromeDriver：Chrome for Testing
- ⚙️ 更新.env文件中的路径配置

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

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

# 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"

Create, schedule, and publish LinkedIn posts directly from Claude Desktop or ChatGPT through natural conversations