XHS Reader MCP
Built by a human who wanted her AI to read what she reads.
**基于 JoeanAmier/XHS-Downloader 二次开发的 MCP 阅读扩展，按 GPL-3.0 开源。**原项目提供笔记信息提取、媒体下载等基础能力，本项目保留其来源和许可，不将这些能力声明为原创。
在原项目基础上，新增公开分享页评论读取、视频抽帧、离线语音转录、异步结果领取及临时媒体自动清理，并将截图以 MCP 图像内容返回给 AI 客户端。可自行部署，无需购买第三方内容 API。具体改动与第三方说明见 NOTICE.md。
这是独立的扩展项目，不是小红书官方服务，也不是原项目作者提供的托管服务。需要自行部署；不附带任何可直接连接的公共服务器或账号。
按设备安装
- Mac 电脑：Mac 安装说明，包含 Intel 与 Apple 芯片的注意事项。
- Windows 电脑：Windows 安装说明，使用 Docker Desktop 的 Linux 容器。
- **Linux / VPS：**继续阅读下方安装步骤。
没有 VPS 也可以尝试本机部署；电脑需要保持开机、联网且 Docker 正在运行。当前提供的是部署步骤，尚未完成 Mac、Windows 或 Apple 芯片的实机验证，不能视为各平台兼容性认证。
功能
视频返回的是抽取的画面和语音识别结果，不是整段原视频，也不在服务器上运行对话大模型。客户端需要能把 MCP 图像内容传给支持图片的模型。仅支持文字工具结果的客户端仍可使用正文、评论和转录。
评论默认最多20条，合法范围1–20；分享页不足20条就只返回实际条数，不翻页、不补造评论。每条最多附带3条页面已有回复。返回 unavailable 表示本次页面没有提供可读取数据，不代表评论区为空。
前提
- Docker Engine 与 Docker Compose v2；推荐 Linux x86_64。
- 本地 Python 3 用于生成私有配置。
- 网络能访问公开上游代码、软件包、模型文件及小红书分享页。
- 视频组件的容器内存上限为1280MB、CPU上限1核；模型约148MB。需要给操作系统和其他服务留余量，未声明支持所有机器架构。
依赖和模型在构建时联网下载；转录在运行时使用本机模型，不调用外部收费转录接口。运行时读取分享链接仍须联网。
安装
先阅读本项目及上游说明，再在本项目目录执行：
python scripts/init_config.py
docker compose build
docker compose up -d
docker compose ps
初始化会生成 private/auth_secret.key、private/token.txt 和空账号Cookie的 private/settings.json。遇到已有配置会停止，不会覆盖。请保护整个 private/；不要提交、分享或截图展示这些文件。
Linux 用户若文件所有者不是UID/GID 1000，将 .env.example 复制为 .env，把 MCP_UID、MCP_GID 分别设为 id -u、id -g 的结果。不要用放开所有文件权限的办法解决读取失败。Windows 的文件权限和Docker挂载行为需自行确认。
首次启动后如果遇到只读设置文件错误，应先核对配置文件与固定上游版本是否匹配，不要把整个主机目录挂进容器。
连接客户端
本机 MCP 地址为 http://127.0.0.1:5556/mcp，类型为 Streamable HTTP。请求头填：
Authorization: Bearer <private/token.txt中的令牌>
从自己的私人终端读取令牌，填写到客户端的私密鉴权栏。不要发给任何人，也不要放进 URL 查询参数。examples/mcp-client.example.json 仅包含保留示例域名和占位令牌。
手机或异机访问需要自行配置 HTTPS 反向代理。examples/Caddyfile.example 是通用片段，示例域名不可直接使用。默认端口仅绑定本机；不要直接把应用端口改为公网开放。
更新后，在客户端刷新 MCP 工具目录。不同客户端是否支持 MCP 图片、异步任务和自定义鉴权头，需要分别实测。
视频调用顺序
- 将完整小红书分享链接或分享文案交给
read_xhs_video。 - 获得
job_id后，每隔约5秒用get_xhs_video_result查询同一个 ID。不要反复提交相同视频。 ready时，将返回的文字和图像一起交给模型分析。- 结果领取一次即从服务器任务表移除；重复领取会返回
not_found。
目前单个视频最长10分钟；默认均匀抽8帧，可设2–12帧，截图宽度不超过960像素。均匀抽帧可能漏掉帧间文字和动作。自动语音识别可能有错字、误识别或遗漏；有音轨但无转录，不足以证明没有人说话。转录超时会明确标记，不假称成功。
内容保存与清理
- 原视频、音频和截图放在256MB的容器临时区；处理结束的
finally中删除，失败时也清理。 - 原下载工具调用结束即删除媒体，不适合作为长期素材下载器。
- 未领取的视频结果只暂存在进程内存，完成后180秒过期，后台每15秒清理一次。领取后立即从任务表移除。
- 评论页面和结果只在内存处理，不写文件、不缓存、不下载评论配图。
- 临时区仍存在上游运行所需的小型数据库或缓存；重建/重启容器会清空临时区。这不是“完全没有文件”。
- 程序、离线模型、认证配置和有轮转上限的运行日志会保留。业务输出已静默，避免将源链接和笔记标题写入普通业务日志。
- 临时文件系统使用内存，宿主可能把内存页换到swap或留下崩溃转储；这不是取证意义的安全擦除保证。
- AI客户端、聊天历史、模型服务商和反向代理有各自的数据保留策略，本服务不能替它们删除内容。
临时空间达到上限会导致任务失败。256MB是整个媒体工作区上限，不是保证可处理256MB大小的视频，抽帧和音频同样需要空间。
验证与维护
本地离线测试：
python -m pip install -r requirements-dev.txt
python -m unittest discover -s tests -v
python scripts/privacy_check.py .
建议在自己的Python虚拟环境中安装测试依赖；安装依赖需要联网，测试本身不请求真实笔记。
启动后验证鉴权和工具目录，不抓取真实笔记：
python scripts/smoke_mcp.py
停止服务用 docker compose stop。保留 private/ 才能继续使用原令牌；不要随意删除认证密钥。升级前核对上游固定提交、依赖及配置，按自己的维护政策准备回退方案。不要在共享服务器上执行全局清理命令。
范围与许可
只处理公开分享页面允许返回的内容，不绕过登录墙、验证码、私密笔记或访问控制；页面不给评论时返回不可用。平台页面、网络及访客策略会变化，不能保证所有链接都可读取，也不能承诺没有访问限制。
本项目不提供登录、发帖、点赞、关注或评论发布。正文来自上游提取器；评论来自公开手机分享页的预载状态，两条路径的可用性可能不同。
项目以GPL-3.0发布。构建会下载固定版本的上游代码并保留其许可证；修改与第三方资源说明见 NOTICE.md。模型和各依赖保留各自许可，不因本仓库许可而改变。转载请保留署名及许可文件。