xiaohongshu-mcp-py

Python rewrite of the Xiaohongshu automation toolchain powered by Playwright + FastMCP. 可直接作为 MCP 服务暴露给 cc或者cherry studio 等客户端。

Overview / 项目简介

通过 Playwright 驱动 Chromium（默认 headless），在 xhs_mcp/xhs 中把「首页、搜索、详情、发布、互动、登录、个人主页」等操作抽象成独立动作。
xhs_mcp/mcp_server.py 把这些动作暴露为标准 MCP Tool，既可通过 streamable-http 远程调用，也可通过 stdio 作为本地子进程集成。
xhs_mcp/cli/login_cli.py 和 scripts/manual_actions.py ：前者专注于扫码登录与 cookies 落地，后者用于对浏览器动作的测试。
Cookies / storage_state 采用 profile + profiles/<name>/cookies.json 的模式保存，同时兼容旧的 /tmp/cookies.json 与 COOKIES_PATH 环境变量，避免破坏历史部署。
内置 scripts/clean_array.py 对抓取到的 feed 数据做简单脱敏（去除 noteCard.user.xsecToken），利于下游安全存储与对外暴露。

Repository Layout / 目录速览

Path	Purpose
`xhs_mcp/xhs/`	Playwright action layer：feeds、搜索、详情、发布、互动、登录、个人主页等动作的实现。
`xhs_mcp/infra/`	浏览器基础设施：Playwright 启动参数（轻量 stealth）、context 管理、cookies 读写。
`xhs_mcp/mcp_server.py`	MCP 服务定义及所有 tool 的适配层，同时处理 debug/trace、参数默认值等。
`xhs_mcp/cli/`	CLI 入口：`mcp_cli` 负责运行 MCP 服务，`login_cli` 负责扫码登录。
`scripts/manual_actions.py`	方便开发者在命令行直接触发 feeds/search/publish 等动作，输出 JSON 结果。
`scripts/clean_array.py`	针对 feed 数据的脱敏清洗工具，可独立运行或作为模块导入。
`profiles/`	Profile 级别的 cookies 存储目录，示例 `profiles/myacc/cookies.json`。

Requirements & Installation / 环境依赖

python -m venv .venv && source .venv/bin/activate  # 推荐使用虚拟环境
pip install -r requirements.txt
playwright install chromium  # 首次运行需要安装浏览器

Minimum runtime: Python 3.11+、Playwright ≥ 1.44、Typer ≥ 0.12、FastMCP (mcp ≥ 0.1)。
部署在服务器上时，可通过 CHROME_BIN 指定自定义 Chromium/Chrome，可更好地规避风控。

Cookies 存储策略（见 xhs_mcp/configs.py）：
- 优先复用历史 /tmp/cookies.json。
- 其次读取 COOKIES_PATH 环境变量。
- 若提供 --profile，会自动使用/创建 profiles/<profile>/cookies.json。
- 也可以显式传入 --cookies-path。
扫码登录流程（python -m xhs_mcp.cli.login_cli）：
- check：确认当前 cookies 是否已登录。
- get_qrcode：抓取二维码图片（data URL 或远程 URL），写入 login.png。
- wait：阻塞等待扫码完成并保存最新 cookies。
- login：一条命令串联 “获取二维码 → 等待登录 → 保存 cookies”，适合部署脚本。
若使用多账号，请为每个账号配置独立 profile 目录，避免 storage_state 相互覆盖。

Running the MCP Server / 启动 MCP 服务

python -m xhs_mcp.cli.mcp_cli serve \
  --host 0.0.0.0 \
  --port 8000 \
  --transport streamable-http \
  --profile myacc \
  --debug-dir debug \
  --trace

--debug-dir 会在每次调用后落地 DOM、截图、console log；配合 --trace 可生成 Playwright trace。
LangGraph / Claude Desktop 接入：在 MultiServerMCPClient 或配置文件中添加 streamable_http endpoint，指向 http://<host>:<port>/mcp。

Available MCP Tools / 可用工具一览

Tool	Purpose	Required params	Notes
`feeds_list`	获取首页推荐 feed 列表	(登录态)	返回值会通过 `clean_array.clean_xsec_tokens` 脱敏。
`search_feeds`	搜索 feed	`keyword`	同样会去除内嵌用户 `xsecToken`。
`feed_detail`	获取笔记详情 + 评论	`feed_id`, `xsec_token`	直接读取 `__INITIAL_STATE__`。
`publish_image`	发布图文笔记	`title`, `content`, `image_paths`	`image_paths` 为本地文件列表，可附带 `tags`。
`publish_video`	发布视频笔记	`title`, `content`, `video_path`	自动等待上传完成再点击发布。
`post_comment`	评论笔记	`feed_id`, `xsec_token`, `content`	通过页面定位编辑框后提交。
`like_feed` / `unlike_feed`	点赞/取消点赞	`feed_id`, `xsec_token`	读取互动状态后避免重复点击。
`favorite_feed` / `unfavorite_feed`	收藏/取消收藏	`feed_id`, `xsec_token`	同步状态判断逻辑与点赞类似。
`user_profile`	查看任意用户主页	`user_id`, `xsec_token`	返回 basic info + interactions + feeds。
`my_profile`	查看当前登录账号主页	(登录态)	通过侧边栏导航进入个人页。
`check_login`	判断当前 cookies 是否有效	–	适合探活。

所有工具均接受 profile / cookies_path / chrome_bin / debug_dir / trace 参数，CLI 层也可以通过 configure_defaults 设定全局默认值。

Run Flow / 项目运行流程

登录应该在 MCP 进程启动之前完成；MCP 服务只消费既有 cookies。

准备依赖（首次执行）

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
playwright install chromium

扫码登录（生成 cookies 文件）
```
python -m xhs_mcp.cli.login_cli login \
  --profile myacc \
  --out login.png \
  --timeout 240
```
- CLI 会无头抓取二维码并写入 login.png，请用手机扫描完成登录。
- 登录成功后，cookies 会保存到 profiles/myacc/cookies.json（或你指定的 --cookies-path）。
- 随时验证会话是否仍有效：
  python -m xhs_mcp.cli.login_cli check --profile myacc
启动 MCP 服务
```
python -m xhs_mcp.cli.mcp_cli serve \
  --host 0.0.0.0 \
  --port 8000 \
  --profile myacc \
  --debug-dir debug
```
- 服务会复用步骤 2 生成的 cookies，debug/ 下会保留 DOM、截图、console 日志。
- 若需要与本地应用直连（Claude Desktop 等），请将 --transport 改为 stdio。
连接客户端 / 验证
可以使用cherry stio：

Debugging & Troubleshooting / 调试与排障

若页面元素无法点击，可使用 PublishImageAction / _PublishBase 中的 _select_tab 逻辑作为参考（包括弹窗移除与 focus 修复）。
profiles/<name>/cookies.json 建议纳入 .gitignore（默认已忽略），避免泄漏。
通过环境变量 PLAYWRIGHT_BROWSERS_PATH 可复用系统级浏览器安装，减少镜像体积。
debug/ 目录下的截图可对照时间戳定位具体请求。
遇到 no feeds found in __INITIAL_STATE__ 等错误，多半是 cookies 过期或页面结构改变，优先使用 login_cli 重新登录并复现。

Development Notes / 开发者提示

代码使用 Python 3.11 的 typing 新语法（list[str] 等），请确保本地解释器版本满足要求。
行为层（xhs_mcp/xhs/*.py）与服务层（xhs_mcp/mcp_server.py）已经解耦，扩展新动作时建议先在 scripts/manual_actions.py 中验证，再注册为 MCP tool。
建议在合并前运行 playwright codegen / trace.viewer 自查元素定位，减少线上改动频率。
欢迎提交 Issue/PR，一起把小红书 MCP 能力覆盖到更多工作流。

Happy automating! ✨