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

配置说明

环境变量

变量名	说明	默认值
HOST	服务器监听地址	0.0.0.0
PORT	服务器端口	18060
HEADLESS	浏览器无头模式	true
BROWSER_BIN_PATH	浏览器二进制路径	自动检测
COOKIES_PATH	Cookie 文件路径	./data/cookies.json
LOG_LEVEL	日志级别	INFO

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 版本的对比

特性	Go 版本	Python 版本
浏览器自动化	go-rod	Playwright
Web 框架	Gin	FastAPI
数据验证	手动	Pydantic
异步支持	Goroutines	asyncio
类型系统	静态类型	类型提示
性能	更快	较慢但足够
开发效率	中等	更高
生态系统	成熟	更丰富

注意事项

浏览器选择器

由于小红书页面结构可能会变化，部分 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。