XHS-CLI / XHS-MCP

面向个人创作者的小红书 MCP 服务器和 CLI 工具，支持内容管理、数据获取、队列发布与 Obsidian 笔记直发。

本项目基于原作者 joohw/xhs-cli 进行修改和定制，感谢原作者及贡献者的开源工作。

Why XHS-CLI

个人创作越来越依赖各种数字工具，却缺少把它们串联起来的粘合剂。XHS-CLI 通过统一的 CLI 与 MCP Server，把浏览器自动化、内容模板、数据接口与 AI 协作能力打包在一起，让创作者可以在本地脚本、自动化服务或智能助手中无缝调用同一套小红书工作流，真正做到“内容策略—素材生成—账号运营”全链路联动。

核心功能

• 🔗 一套 CLI/MCP 接口即可连接浏览器自动化、脚本和 AI，构建属于自己的内容工作流
• 📥 扫描并缓存历史笔记，作为上下文喂给智能助手或自动化流程
• 🎯 按模板生成新内容、封面与素材，确保账号调性一致
• 📊 拉取运营/画像数据并序列化输出，便于可视化或进一步分析
• 🚀 将发布、排期、素材管理全流程开放出来，方便接入任何数字工具链
• 📝 从 Obsidian Front Matter 读取标题、标签与图片，发布后自动写回状态和链接

安装

# 全局安装（推荐）
npm install -g xhs-post

注意：

• 本包在安装时不会下载 Chromium（减少安装体积），会自动使用系统已安装的 Chrome/Chromium 浏览器
• 如果系统没有安装 Chrome/Chromium，请先安装 Chrome 浏览器，再运行 xhs login

前置要求

• Node.js >= 18.0.0
• Chrome/Chromium 浏览器（Puppeteer 需要）

快速开始

1. 登录

xhs login

这会打开浏览器，让你登录小红书账号。

xhs-cli 不会单独保存账号密码，登录状态保存在本地浏览器数据目录中。

2. 检查登录状态

xhs check-login

3. 退出登录

xhs logout

这会清除保存在 ~/.xhs-mcp/browser-data 下的浏览器缓存文件，下次需要重新登录。

如只需关闭浏览器并保留登录状态：

xhs stop

4. 获取账号信息

xhs get-my-profile

5. 从 Obsidian 笔记直接发布

xhs publish-obsidian /absolute/path/to/note.md

Obsidian 笔记需要 Front Matter，且 publish_status 为 ready。当前支持 publish_asset_mode: assets_output，图片读取自 <assets>/output/*.png，并且必须为 PNG 文件。发布标签仅取自 publish_social_tags，正文里的 Obsidian 标签不会作为小红书标签。

如需重试其他状态的笔记，可增加 --force。完整字段、状态回写与重试规则见 发布指南。

可用命令

账号管理

# 登录小红书账号
xhs login

# 退出登录并清除缓存
xhs logout

# 关闭浏览器但保留登录状态
xhs stop

# 检查登录状态
xhs check-login

# 获取用户资料
xhs get-my-profile

数据获取

# 获取运营数据
xhs get-operation-data

# 获取近期笔记列表
xhs get-recent-notes

# 根据笔记 ID 获取笔记详情
xhs get-note-detail <noteId>

内容发布

# 创建待发布笔记
xhs write-post --title "标题" --content-file ./content.txt --image-dir ./images

# 也可以直接传入内容和多张图片
xhs write-post --title "标题" --content "正文" --image ./1.png --image ./2.png

# 发布队列中的 post
xhs post [filename]

# 列出待发布的 post
xhs list-post

# 直接发布 Obsidian 笔记
xhs publish-obsidian /absolute/path/to/note.md

# 强制重试非 ready 状态的 Obsidian 笔记
xhs publish-obsidian /absolute/path/to/note.md --force

查看帮助

xhs

运行不带参数会显示所有可用命令的详细说明。

MCP 服务器

这个包同时也是一个 MCP（Model Context Protocol）服务器，可以与支持 MCP 的客户端（如 Cursor、Claude Desktop 等）集成。

xhs setup-mcp

可通过 --claude、--cursor 或 --all 指定需要配置的客户端。

本地开发时也可以运行：

npm run mcp

功能特性

• ✅ 完整的 TypeScript 支持
• ✅ 缓存机制保护账号访问频率
• ✅ 命令行工具，易于使用
• ✅ MCP 协议支持，可集成 AI 工具
• ✅ 支持文件内容、单张图片和图片目录输入
• ✅ 支持 Obsidian 笔记直发及发布状态回写
• ✅ 面向个人创作者设计

许可证

MIT

相关链接

• 当前项目仓库
• 问题反馈
• 上游项目 joohw/xhs-cli