Which integrations are available for this server?

Provides tools for interacting with Xiaohongshu (Red), enabling capabilities such as managing login sessions, searching and browsing feeds, viewing user profiles, interacting with content through likes and comments, and publishing image or video posts.

How do I use Xiaohongshu MCP Python?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Xiaohongshu MCP Python search for the best camping spots near Shenzhen" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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 文件路径优先级：

/tmp/cookies.json（向后兼容）
环境变量 COOKIES_PATH
当前目录 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 工具：

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

开发指南

添加新功能

在 xiaohongshu/ 目录下创建新的模块文件
在 service.py 中添加对应的服务方法
在 mcp_server.py 中注册 MCP 工具
在 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 选择器可能需要更新。如果遇到元素找不到的错误，请检查：

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

发布功能

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

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

性能优化

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

故障排除

浏览器启动失败

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

检查 Cookie 文件路径和权限：

ls -la data/cookies.json

端口被占用

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

贡献指南

欢迎提交 Issue 和 Pull Request！

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

许可证

MIT License

致谢

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

联系方式

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