Xiaohongshu MCP Python

小红书 MCP 服务器的 Python 实现，从 Go 版本完整重构而来。

功能特性

核心功能

• ✅ 登录管理：二维码登录、登录状态检查、Cookie 管理
• ✅ 内容浏览：Feed 列表、搜索、详情查看
• ✅ 互动功能：评论、回复、点赞、收藏
• ✅ 用户信息：用户主页查看
• ✅ 内容发布：图文发布、视频发布（骨架已实现）
• ✅ MCP 协议：完整的 MCP 工具集成
• ✅ HTTP API：REST API 接口

技术栈

• Web 框架：FastAPI
• 浏览器自动化：Playwright
• MCP 协议：MCP Python SDK
• 数据验证：Pydantic
• 日志：Loguru
• 部署：Docker + Docker Compose

项目结构

xiaohongshu-python/
├── xiaohongshu/           # 业务逻辑包
│   ├── __init__.py
│   ├── types.py           # 数据模型
│   ├── navigate.py        # 页面导航
│   ├── login.py           # 登录功能
│   ├── feeds.py           # Feed 列表
│   ├── search.py          # 搜索功能
│   ├── feed_detail.py     # 详情获取
│   ├── comment_feed.py    # 评论功能
│   ├── like_favorite.py   # 点赞收藏
│   ├── user_profile.py    # 用户主页
│   ├── publish.py         # 图文发布
│   └── publish_video.py   # 视频发布
├── browser/               # 浏览器管理
│   ├── __init__.py
│   └── browser.py
├── cookies/               # Cookie 管理
│   ├── __init__.py
│   └── cookies.py
├── configs/               # 配置管理
│   ├── __init__.py
│   └── settings.py
├── errors/                # 错误处理
│   ├── __init__.py
│   └── errors.py
├── service.py             # 业务服务层
├── mcp_server.py          # MCP 服务器
├── routes.py              # HTTP 路由
├── app_server.py          # 应用服务器
├── main.py                # 主程序入口
├── requirements.txt       # Python 依赖
├── Dockerfile             # Docker 配置
├── docker-compose.yml     # Docker Compose 配置
├── .env.example           # 环境变量示例
└── README.md              # 项目文档

快速开始

方式 1：本地运行

1. 安装依赖

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

# 安装 Playwright 浏览器
playwright install chromium

2. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，根据需要修改配置

3. 启动服务

python main.py

服务将在 http://localhost:18060 启动。

方式 2：Docker 运行

1. 构建镜像

docker-compose build

2. 启动服务

docker-compose up -d

3. 查看日志

docker-compose logs -f

4. 停止服务

docker-compose down

配置说明

环境变量

Cookie 管理

Cookie 文件路径优先级：

1. /tmp/cookies.json（向后兼容）
2. 环境变量 COOKIES_PATH
3. 当前目录 cookies.json

API 文档

HTTP API

启动服务后，访问 http://localhost:18060/docs 查看完整的 API 文档（Swagger UI）。

主要端点

登录相关

• GET /api/v1/login/status - 检查登录状态
• GET /api/v1/login/qrcode - 获取登录二维码
• DELETE /api/v1/login/cookies - 删除 cookies

Feed 相关

• GET /api/v1/feeds/list - 获取 Feed 列表
• POST /api/v1/feeds/search - 搜索内容
• POST /api/v1/feeds/detail - 获取 Feed 详情

评论相关

• POST /api/v1/feeds/comment - 发表评论
• POST /api/v1/feeds/comment/reply - 回复评论

用户相关

• POST /api/v1/user/profile - 获取用户主页

发布相关

• POST /api/v1/publish - 发布图文内容
• POST /api/v1/publish_video - 发布视频内容

MCP 工具

支持以下 13 个 MCP 工具：

1. check_login_status - 检查登录状态
2. get_login_qrcode - 获取登录二维码
3. delete_cookies - 删除 cookies
4. list_feeds - 获取 Feed 列表
5. search_feeds - 搜索内容
6. get_feed_detail - 获取 Feed 详情
7. post_comment_to_feed - 发表评论
8. reply_comment_in_feed - 回复评论
9. like_feed - 点赞/取消点赞
10. favorite_feed - 收藏/取消收藏
11. user_profile - 获取用户主页
12. publish_content - 发布图文内容
13. publish_with_video - 发布视频内容

开发指南

添加新功能

1. 在 xiaohongshu/ 目录下创建新的模块文件
2. 在 service.py 中添加对应的服务方法
3. 在 mcp_server.py 中注册 MCP 工具
4. 在 routes.py 中添加 HTTP 端点

运行测试

# TODO: 添加测试
pytest tests/

代码格式化

# 使用 black 格式化代码
black .

# 使用 isort 排序导入
isort .

# 使用 flake8 检查代码
flake8 .

与 Go 版本的对比

注意事项

浏览器选择器

由于小红书页面结构可能会变化，部分 CSS 选择器可能需要更新。如果遇到元素找不到的错误，请检查：

1. 页面是否完全加载
2. CSS 选择器是否正确
3. 是否需要登录

发布功能

图文发布和视频发布功能的骨架已实现，但具体的上传逻辑需要根据实际页面结构完善：

• 图片/视频上传
• 标签添加
• 发布确认

性能优化

• 使用页面池复用浏览器页面
• 实现请求缓存
• 优化图片加载策略

故障排除

浏览器启动失败

# 安装 Playwright 浏览器
playwright install chromium
playwright install-deps chromium

Cookie 加载失败

检查 Cookie 文件路径和权限：

ls -la data/cookies.json

端口被占用

修改 .env 文件中的 PORT 配置。

贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

许可证

MIT License

致谢

• 原 Go 版本：xiaohongshu-mcp
• Playwright：https://playwright.dev/python/
• FastAPI：https://fastapi.tiangolo.com/
• MCP：https://modelcontextprotocol.io/

联系方式

如有问题或建议，请提交 Issue。