xiaohongshu-mcp-py

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

Table of Contents

1. Overview / 项目简介

2. Repository Layout / 目录速览

3. Requirements & Installation / 环境依赖

4. Login & Session Management / 登录与会话管理

5. Running the MCP Server / 启动-mcp-服务

6. Available MCP Tools / 可用工具一览

7. Manual CLIs & Utilities / 手动调试工具

8. Debugging & Troubleshooting / 调试与排障

9. Development Notes / 开发者提示

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 / 目录速览

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，可更好地规避风控。

Login & Session Management / 登录与会话管理

1. Cookies 存储策略（见 xhs_mcp/configs.py）：

   • 优先复用历史 /tmp/cookies.json。

   • 其次读取 COOKIES_PATH 环境变量。

   • 若提供 --profile，会自动使用/创建 profiles/<profile>/cookies.json。

   • 也可以显式传入 --cookies-path。

2. 扫码登录流程（python -m xhs_mcp.cli.login_cli）：

   • check：确认当前 cookies 是否已登录。

   • get_qrcode：抓取二维码图片（data URL 或远程 URL），写入 login.png。

   • wait：阻塞等待扫码完成并保存最新 cookies。

   • login：一条命令串联 “获取二维码 → 等待登录 → 保存 cookies”，适合部署脚本。

3. 若使用多账号，请为每个账号配置独立 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 / 可用工具一览

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

Run Flow / 项目运行流程

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

1. 准备依赖（首次执行）

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

2. 扫码登录（生成 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

3. 启动 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。

4. 连接客户端 / 验证

   可以使用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! ✨