工具包

Name: 工具包
Author: aki66938

作者：aki66938794 星标更新：2025-07-10

安装使用来源：spider==github.com

项目介绍

📕 小红书创作者MCP工具包

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

✨ 主要特性

🍪 Cookie管理安全地获取、验证和管理小红书的登录凭证
🤖 MCP协议支持无缝集成AI客户端，如Claude Desktop和CherryStudio
📝 自动发布支持图形、文本和视频笔记的自动化发布
🖼️ 多样化图像支持支持本地图像和网络URL
⏰ 定时任务支持使用cron表达式的定时数据收集
📊 数据收集自动收集创作者中心仪表板、内容分析和粉丝数据
🧠 AI数据分析中文表头数据，AI可以直接理解和分析
💾 数据存储支持CSV本地存储（SQL目前预留未开发）
🎯 统一接口解决小红书上LLM操作自动化需求的工具

📋 功能列表

内容发布

[x] 图文发布 -支持发布图形和文本笔记
[x] 视频发布 -支持发布视频笔记
[x] 话题标签 -支持自动添加话题标签以增加内容曝光
[ ] 内容搜索 -支持指定搜索（开发计划中）

数据收集

[x] 仪表盘数据 -收集账户概览数据（粉丝数、点赞数等）
[x] 内容分析数据 -收集笔记表现数据（浏览量、点赞数等）
[x] 粉丝数据 -收集粉丝增长和分析数据
[x] 定时收集 -支持使用cron表达式的自动定时收集
[x] 数据存储 -CSV本地存储（默认）

📋 环境要求

🌐 浏览器环境

Google Chrome浏览器（推荐最新版本）
ChromeDriver（版本必须与Chrome版本完全匹配）

🔍 查看Chrome版本

在Chrome浏览器中访问：chrome://version/

chrome版本

📥 Chrome Driver安装方法

方法1：自动下载（推荐）

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

方法2：手动下载

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

方法3：包管理器安装

# macOS (Homebrew)
brew install --cask chromedriver

# Windows (Chocolatey)  
choco install chromedriver

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

⚠️ 重要通知版本不匹配是最常见的问题原因，请确保Chrome Driver版本与Chrome浏览器版本完全一致！

🌐 远程浏览器连接

支持连接到正在运行的远程Chrome实例，以提高性能并支持远程部署场景。

🔧 配置方法

在.env文件中添加以下配置：

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

🚀 启动远程Chrome

如果出现没有权限的错误，请检查./chrome-data目录是否有读写权限。如果没有，请按照以下步骤进行修复
1. docker run --rm selenium/standalone-chrome id seluser 获取seluser的UID，例如返回 uid=1200(seluser) gid=1200(seluser) groups=1200(seluser)
2. sudo chown -R 1200:1200 ./chrome-data 授予seluser读写权限，1200是seluser的UID
3. 重新执行 docker-compose up --force-recreate 启动容器

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"

💡 使用场景

远程部署在服务器上运行Chrome，使用本地连接
性能优化复用正在运行的Chrome实例，避免重复启动
开发和调试连接到已登录的Chrome实例，维持会话状态
Docker环境在容器之间共享Chrome实例

⚠️ 注意事项

远程连接时不会启动新的Chrome实例
确保目标Chrome实例已启用远程调试功能
有些操作（如窗口调整大小）可能在远程模式下不被支持

🚀 快速开始

💡 最简使用方法

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

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

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

🎮 交互式菜单

运行 ./xhs 后会显示友好的菜单界面：

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

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

🛠️ 从源码运行

方法1：UV（推荐） ⚡)

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

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

💡 UV使用提示：所有python命令都可以替换为uv run python，享受更快的依赖管理体验！

方法2：pip（传统方法）

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

🛠️ 用户指南

1. 创建配置文件

复制并编辑配置文件：

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

必需配置：

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

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

2. 获取登录凭证

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

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

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

登录小红书创作者中心
确保正常访问创作者中心功能
完成后按回车键保存

3. 启动MCP服务器

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

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

4. 客户端配置

Claude Desktop

使用UV（推荐）

在 ~/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"
      ]
    }
  }
}

使用系统Python

如果未使用UV，可以配置为：

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

cherry studio

在MCP配置中添加

Cherry Studio配置

n8n

在n8n AI代理节点的工具中添加配置设置

n8n的AI代理配置

🔧 主要功能

MCP工具列表

工具名称	功能描述	参数	备注
`test_connection`	测试MCP连接	无	连接状态检查
`smart_publish_note`	在小红书上发布笔记 ⚡	标题、内容、图片、视频、标签、话题	支持本地路径、网络URL和话题标签
`check_task_status`	检查发布的任务状态	task_id	查看任务进度
`get_task_result`	获取已完成任务的结果	task_id	获取最终发布结果
`login_xiaohongshu`	在小红书上智能登录	force_delogin, quick_mode	MCP专用非交互登录
`get_creator_data_analysis`	获取创作者数据用于分析	无	AI数据分析专用

💬 AI对话操作指南

通过与AI对话，可以完成登录、发布、数据分析等操作，无需学习复杂的命令。

🔐 智能登录

用户："登录小红书"

重要通知：

🚨 第一次使用时请勿修改headless参数，获取cookies后再切换到无头模式
🌐 调用登录工具后，AI会拉起浏览器，首次登录需要手动输入验证码或扫描二维码
🍪 成功后会自动保存cookies，下次登录可免去此步骤

📝 内容发布

图文发布（本地图片）：

请发布一篇小红书笔记，标题："今日分享"，内容："..."，图片路径："/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秒检查一次精确文本匹配

📊 数据收集和AI分析功能

自动从小红书创作者处收集数据，支持定时任务和AI智能分析。

🧠 AI数据分析功能

中文表头CSV文件使用中文表头，AI可以直接理解数据含义
智能分析通过get_creator_data_analysis MCP工具获取完整数据
数据驱动AI基于真实数据提供内容优化建议
趋势分析分析账户表现趋势和粉丝增长

收集的数据类型

仪表盘数据账户概览数据，如粉丝数、收到的点赞数和页面浏览量
内容分析数据记录表现数据，包括浏览量、点赞数、评论等
粉丝数据粉丝增长趋势、粉丝画像分析等

定时任务示例

使用cron语法编写配置文件.env

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

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

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

🎯 手动操作工具

添加交互式菜单和手动操作工具，提供更便捷的操作体验：

主要功能

🔄 数据收集手动触发数据收集，支持选择数据类型和时间维度
🌐 浏览器操作快速打开已登录的小红书页面
📊 数据管理导出Excel/JSON，分析数据趋势，备份和恢复
🍪 Cookie管理检索、查看和验证cookie状态

使用示例

# 启动交互式菜单
./xhs

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

🚀 更新日志 - v1.3.0

🎯 重要功能更新

🏷️ 话题标签自动化功能（完整实现）

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

工具包