xiaohongshu-automation 2.0.5

基于 Model Context Protocol (MCP) 的小红书自动化解决方案

小红书自动化工具

基于 Model Context Protocol (MCP) 的小红书自动化解决方案，为 AI 助手提供内容发布、评论管理和系统监控能力。

✨ 新功能：多账号支持

🎉 版本 2.0 重大更新！

多账号实现逻辑，现已支持多个小红书账号同时管理和操作：

多账号功能特性

• ✅ 多账号管理: 支持添加、删除、切换多个小红书账号
• ✅ 独立认证: 每个账号使用独立的cookie文件存储
• ✅ 批量操作: 可同时使用多个账号进行发布、搜索、评论
• ✅ 账号隔离: 各账号间完全隔离，避免登录冲突
• ✅ 向后兼容: 完全兼容原有的单账号使用方式

快速体验多账号功能

import requests

# 1. 添加多个账号
accounts = ["13800138000", "13900139000", "13700137000"]
for phone in accounts:
    requests.post("http://localhost:8000/account/add", json={"phone_number": phone})

# 2. 批量发布到不同账号
for phone in accounts:
    requests.post("http://localhost:8000/publish", json={
        "pic_urls": ["https://example.com/image.jpg"],
        "title": f"账号 {phone} 的内容",
        "content": "多账号测试内容",
        "phone_number": phone
    })

详细使用说明请参考：多账号功能指南

🚀 快速开始

1. 环境准备

推荐使用 uv 进行环境管理（更快更现代的Python包管理器）

# 安装 uv（如果还没安装）
# Windows: 
curl -LsSf https://astral.sh/uv/install.ps1 | powershell
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆项目
git clone <repository-url>
cd xiaohongshu-automation

# 方式一：使用 uv（推荐）
uv venv                    # 创建虚拟环境
uv sync                    # 安装所有依赖

# 方式二：传统方式
python -m venv venv
venv\Scripts\activate      # Windows
# source venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

🛠️ 开发环境一键设置

方式一：使用便捷脚本（Windows）

# 一键设置开发环境
scripts\setup_dev.bat

方式二：使用 uvx 快速测试（推荐）

无需克隆代码，直接测试最新版本：

# 快速启动 FastAPI 服务器（从 PyPI）
uvx --from xiaohongshu-automation xhs-server

# 快速启动 MCP 服务器（从 PyPI）
uvx --from xiaohongshu-automation xhs-mcp

# 从 Git 仓库直接运行最新开发版
uvx --from git+https://github.com/A1721/xiaohongshu-automation.git xhs-server

# 测试特定版本
uvx --from xiaohongshu-automation==1.0.0 xhs-server

方式三：传统开发环境

# 克隆项目
git clone <repository-url>
cd xiaohongshu-automation

# 使用 uv（推荐）
uv venv                    # 创建虚拟环境
uv sync                    # 安装所有依赖

# 或传统方式
python -m venv venv
venv\Scripts\activate      # Windows
# source venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

📦 打包和发布

# 构建包
uv build

# 使用 uvx 测试本地构建的包
uvx --from ./dist/xiaohongshu_automation-1.0.0-py3-none-any.whl xhs-server
uvx --from ./dist/xiaohongshu_automation-1.0.0-py3-none-any.whl xhs-mcp

# 发布到 PyPI（使用便捷脚本）
scripts\publish.bat

# 或手动发布
uv pip install twine
twine upload dist/*

# 测试发布到 TestPyPI
twine upload --repository testpypi dist/*

# 使用 uvx 测试 TestPyPI 版本
uvx --index-url https://test.pypi.org/simple/ --from xiaohongshu-automation xhs-server

2. 启动服务

重要: 必须按顺序启动两个服务

# 第一步：启动 FastAPI 后端服务并且扫码登录小红书
python main.py

# 第二步：启动 MCP 服务器
python mcp_server.py

2. 配置 AI 客户端

在支持 MCP 的 AI 客户端中配置连接到本地 MCP 服务器。

📦 安装发布版本

方式一：传统安装

如果项目已发布到 PyPI，用户可以直接安装：

pip install xiaohongshu-automation

方式二：使用 uvx（推荐）

uvx 是 uv 的一个强大功能，可以直接运行 Python 包而无需先安装到当前环境，非常适合运行 CLI 工具和一次性任务。

优势

• 🚀 无需安装: 直接运行包，不污染当前环境
• ⚡ 自动管理: 自动创建临时环境和依赖管理
• 🔒 隔离运行: 每次运行都在独立环境中
• 💾 缓存优化: 自动缓存环境，再次运行更快

使用方法

# 直接运行 FastAPI 服务器
uvx --from xiaohongshu-automation xhs-server

# 直接运行 MCP 服务器
uvx --from xiaohongshu-automation xhs-mcp

# 运行特定脚本（如果包提供）
uvx --from xiaohongshu-automation --help

# 指定版本运行
uvx --from xiaohongshu-automation==1.0.0 xhs-server

# 从 TestPyPI 运行（测试版本）
uvx --index-url https://test.pypi.org/simple/ --from xiaohongshu-automation xhs-server

开发者使用 uvx

# 从本地构建的包运行
uvx --from ./dist/xiaohongshu_automation-1.0.0-py3-none-any.whl xhs-server

# 从 Git 仓库直接运行
uvx --from git+https://github.com/A1721/xiaohongshu-automation.git xhs-server

方式三：从源码安装

# 克隆项目
git clone <repository-url>
cd xiaohongshu-automation

# 使用 uv 安装
uv pip install -e .

# 或使用 pip 安装
pip install -e .

🛠️ 故障排除

常见问题：MCP调用成功但AI显示失败

症状: MCP服务调用成功，但AI执行结果显示失败 原因: FastAPI后端服务未运行 解决: 运行 python main.py 启动后端服务

详细故障排除指南请参考：TIMEOUT_TROUBLESHOOTING.md

快速诊断

# 运行诊断工具
python test_timeout_improvements.py

# 或在MCP中调用
xiaohongshu_timeout_diagnostic

⚙️ 功能特性

🎯 核心工具

1. xiaohongshu_publish - 发布内容到小红书

   • 支持多张图片（1-18张）
   • 内容质量分析和优化建议
   • 智能话题标签和@用户检测

2. xiaohongshu_get_comments - 获取评论分析

   • 情感分析和关键词提取
   • 评论统计和互动分析

3. xiaohongshu_reply_comments - 批量回复评论

   • 智能回复建议和内容优化
   • 批量处理和语调调整

4. xiaohongshu_monitor - 系统监控

   • 健康状态评分
   • 服务状态检查
   • 历史记录分析

5. xiaohongshu_timeout_diagnostic - 超时诊断 🆕

   • 网络连接测试
   • 性能分析
   • 配置建议

6. xiaohongshu_search_notes - 搜索笔记 🆕

   • 根据关键词搜索相关笔记
   • 支持结果数量限制（1-20条）
   • 返回笔记标题和链接

7. xiaohongshu_get_note_content - 获取笔记内容 🆕

   • 抓取笔记的详细内容
   • 提取标题、作者、发布时间和正文
   • 智能区分正文和评论内容

8. xiaohongshu_analyze_note - 分析笔记内容 🆕

   • 深度分析笔记内容质量和领域归属
   • 智能提取关键词和主题标签
   • 生成内容质量评估报告

9. xiaohongshu_post_comment - 发布评论内容 🆕

   • 指定某个笔记下面发布置顶评论内容

📚 资源

• xiaohongshu://monitor/status - 实时监控状态
• xiaohongshu://posts/history - 发布历史记录
• xiaohongshu://tools/info - 工具信息总览

🎨 提示模板

• xiaohongshu_content_template - 内容创作模板
• xiaohongshu_reply_template - 评论回复模板
• xiaohongshu_optimization_tips - 优化建议模板

📋 API 接口

发布内容

POST /publish
Content-Type: application/json

{
  "pic_urls": ["https://example.com/image1.jpg"],
  "title": "标题",
  "content": "内容文本"
}

获取评论(暂未完善)

GET /get_comments?url=https://www.xiaohongshu.com/explore/xxxxx

回复评论(暂未完善)

POST /post_comments?url=https://www.xiaohongshu.com/explore/xxxxx
Content-Type: application/json

{
  "comment_id_1": ["回复内容1", "回复内容2"],
  "comment_id_2": ["回复内容3"]
}

搜索笔记 🆕

GET /search_notes?keywords=美食&limit=5

获取笔记内容 🆕

GET /get_note_content?url=https://www.xiaohongshu.com/explore/xxxxx

分析笔记 🆕

GET /analyze_note?url=https://www.xiaohongshu.com/explore/xxxxx

⚙️ 配置选项

超时配置

# 基本超时设置
export FASTAPI_TIMEOUT=30          # 默认超时
export PUBLISH_TIMEOUT=60          # 发布操作超时
export COMMENTS_TIMEOUT=30         # 评论操作超时
export MONITOR_TIMEOUT=15          # 监控操作超时
export CONTENT_TIMEOUT=60          # 内容获取超时 🆕
export ANALYSIS_TIMEOUT=70         # 内容分析超时 🆕
export HEALTH_CHECK_TIMEOUT=5      # 健康检查超时

# 重试机制
export ENABLE_AUTO_RETRY=true      # 启用自动重试
export MAX_RETRIES=3               # 最大重试次数
export RETRY_DELAY=2               # 重试间隔（秒）

# 日志配置
export LOG_LEVEL=INFO              # 日志级别
export DETAILED_ERROR_MSG=true     # 详细错误信息

环境配置示例

本地开发

export FASTAPI_TIMEOUT=30
export PUBLISH_TIMEOUT=60
export ENABLE_AUTO_RETRY=true
export MAX_RETRIES=3

生产环境

export FASTAPI_TIMEOUT=60
export PUBLISH_TIMEOUT=120
export ENABLE_AUTO_RETRY=true
export MAX_RETRIES=5
export RETRY_DELAY=3

内容获取配置

# 内容获取超时设置
export CONTENT_TIMEOUT=60          # 笔记内容获取超时

🧪 测试

运行测试套件

# 基础功能测试
python test_mcp_server.py

# 超时和诊断测试
python test_timeout_improvements.py

# 发布功能专项测试
python test_publish_fix.py

# 搜索功能测试 🆕
python test_search_functionality.py

# 内容抓取功能测试 🆕
python test_content_functionality.py

# 内容分析功能测试 🆕
python test_analyze_functionality.py

性能监控

# 启用详细日志
export LOG_LEVEL=DEBUG
python mcp_server.py

# 监控系统状态
xiaohongshu_monitor

🏗️ 项目结构

xiaohongshu-automation/
├── main.py                     # FastAPI 主服务
├── mcp_server.py              # MCP 服务器
├── config.py                  # 配置管理
├── adapters/
│   └── xiaohongshu_adapter.py # 服务适配器
├── tools/                     # MCP 工具
│   ├── base_tool.py          # 基础工具类
│   ├── publish_tool.py       # 发布工具
│   ├── comments_tool.py      # 评论工具
│   ├── monitor_tool.py       # 监控工具
│   ├── timeout_diagnostic_tool.py # 诊断工具 🆕
│   ├── search_tool.py        # 搜索工具 🆕
│   ├── content_tool.py       # 内容抓取工具 🆕
│   ├── analysis_tool.py      # 内容分析工具 🆕
│   └── tool_manager.py       # 工具管理器
├── xiaohongshu_tools.py       # 核心功能模块
├── unti.py                    # 工具函数
├── requirements.txt           # Python 依赖
├── TIMEOUT_TROUBLESHOOTING.md # 故障排除指南 🆕
└── README.md                  # 项目文档

🔒 依赖

• Python 3.8+
• FastAPI - Web 框架
• MCP (Model Context Protocol) - AI 集成协议
• httpx - HTTP 客户端
• pydantic - 数据验证
• selenium - 浏览器自动化
• requests - HTTP 请求

📈 版本历史

v1.0.0 (2025-06-01)

• ✅ 基础 MCP 服务器实现
• ✅ 核心工具集（发布、评论、监控）
• ✅ 智能重试和超时配置
• ✅ 超时诊断工具
• ✅ 笔记搜索功能 🆕
• ✅ 笔记内容抓取功能 🆕
• ✅ 笔记内容分析功能 🆕
• ✅ 详细的故障排除指南

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进项目。

📄 许可证

MIT License

---

🆘 获取帮助

如果遇到问题：

1. 查看故障排除指南: TIMEOUT_TROUBLESHOOTING.md
2. 运行诊断工具: python test_timeout_improvements.py
3. 检查服务状态: 确保 python main.py 正在运行
4. 查看日志: 启用 LOG_LEVEL=DEBUG 获取详细信息

快速检查清单:

• FastAPI 服务已启动 (python main.py)
• MCP 服务器已启动 (python mcp_server.py)
• 可以访问 http://localhost:8000/docs
• AI 客户端正确配置了 MCP 连接

---

最后更新: 2025-06-01