xhs-mcp-py

小红书 MCP 工具的 Python 实现，基于 Playwright 浏览器自动化，支持登录、发布、搜索、点赞、收藏、评论等功能。

特性

• 🔐 扫码登录 - 支持二维码扫码登录，自动保存 cookies
• 📝 发布内容 - 支持发布图文、视频、文字配图，支持定时发布
• 🔍 搜索内容 - 支持关键词搜索（高级筛选能力在 MCP API 中提供）
• ❤️ 互动功能 - 支持点赞、收藏、评论、回复评论
• 📊 数据获取 - 获取首页推荐、笔记详情、用户主页，支持高级评论加载配置
• 🤖 MCP 协议 - 支持 MCP 协议，可与 AI 助手集成

安装

pip install xhs-mcp-py

# 首次运行需安装浏览器
playwright install chromium

快速开始

使用流程

1. 首次使用必须先登录：运行 xhs-mcp login-browser 弹出浏览器登录 或 xhs-mcp login-qrcode --terminal 在终端中显示二维码登录
2. 检查登录状态：运行 xhs-mcp status（输出 ✅ 已登录 或 ❌ 未登录）
3. 执行操作：登录成功后即可使用各种功能
4. Cookies 有效期：约 7-30 天，过期后需重新登录

💡 MCP 使用提示：让 AI 助手先调用 check_login_status 检查登录状态，如果未登录：

• 通过 MCP：调用 login_with_browser
• 或直接在命令行执行：xhs-mcp login-browser

MCP 客户端配置

Claude Desktop

编辑配置文件

• ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "xiaohongshu": {
      "command": "xhs-mcp",
      "args": ["serve"]
    }
  }
}

如果 xhs-mcp 不在系统 PATH 中，使用完整路径：

{
  "mcpServers": {
    "xiaohongshu": {
      "command": "/path/to/your/python/bin/xhs-mcp",
      "args": ["serve"]
    }
  }
}

可通过 which xhs-mcp（macOS/Linux）或 where xhs-mcp（Windows）查看完整路径。

配置完成后重启 Claude Desktop。

Claude Code

# 添加 MCP 服务
claude mcp add xhs-mcp -- xhs-mcp serve

# 查看已添加的 MCP
claude mcp list

# 移除 MCP 服务
claude mcp remove xhs-mcp

Cursor

在 Cursor 设置中添加 MCP 配置：

1. 打开 Cursor Settings → Features → MCP Servers
2. 点击 "Add Server"
3. 填写：
   • Name: xhs-mcp
   • Command: xhs-mcp serve

其他 MCP 客户端

任何支持 MCP 协议的客户端都可以使用，启动命令为：

xhs-mcp serve

发布

图文

图：~/Downloads/vc.png

文字标题：Vibe Coding 真的心累💔

文字正文内容：强如 Opus，也只是傻乎乎地解决当下的指令...

就拿我的项目来说👇
App有两个登录渠道：
✅ 浏览器登录 ← 先调试好了
✅ 二维码登录 ← 后调试的

结果你猜怎么着？
浏览器登录的逻辑直接被二维码登录给复用覆盖了！😅

AI不会帮你考虑整体架构
它只看「现在」要解决的问题
就像装修师傅：你让他修灯，他可能把你刚装好的开关拆了😂

标签：#VibeCoding #AI #Claude #Agent #Opus

文字配图

封面文字：我开源了个小红书自动发布工具：xhs-mcp-py

文字标题：我开源了个小红书自动发布工具：xhs-mcp-py

文字正文内容：
我开源了个小红书自动发布工具：xhs-mcp-py。

基于 Python，轻松兼容 Windows、Mac、Linux。
支持 Claude Code 和 OpenClaw，还能发布文字配图笔记。
核心原理：模拟浏览器登录。

项目地址：https://github.com/luweizheng/xhs-mcp-py

欢迎来玩！

命令行使用

# 1. 扫码登录（首次使用必须执行）
# 方式一：打开浏览器窗口扫码
xhs-mcp login-browser

# 方式二：在终端显示二维码，在 Claude Code、Open Code 中推荐使用这种
# 注意：需要安装 zbar 库（macOS: brew install zbar，Ubuntu: apt install libzbar0）
# 如果未安装 zbar，会自动保存二维码图片并提示路径
xhs-mcp login-qrcode --terminal

# 方式三：保存二维码图片，在 OpenClaw 中将 qrcode.png 发送给 Channel 中的用户
xhs-mcp login-qrcode --save qrcode.png

# 2. 检查登录状态（确认已登录后再执行其他操作）
xhs-mcp status

# 发布图文
xhs-mcp publish -t "标题" -c "文字正文内容" -i image1.jpg -i image2.jpg --tag 旅行 --tag 美食

# 发布视频
xhs-mcp publish-video -t "标题" -c "文字正文内容" -v video.mp4

# 发布文字配图（将文字生成为卡片图片）
xhs-mcp publish-text-card -c "封面文字" -p "第一页内容" -p "第二页内容" -s "基础" -t "笔记标题"

# 搜索内容
xhs-mcp search -k "关键词"

# 点赞/取消点赞
xhs-mcp like --feed-id FEED_ID --xsec-token XSEC_TOKEN
xhs-mcp like --feed-id FEED_ID --xsec-token XSEC_TOKEN --unlike

# 收藏/取消收藏
xhs-mcp favorite --feed-id FEED_ID --xsec-token XSEC_TOKEN
xhs-mcp favorite --feed-id FEED_ID --xsec-token XSEC_TOKEN --unfavorite

# 发表评论
xhs-mcp comment --feed-id FEED_ID --xsec-token XSEC_TOKEN -c "评论内容"

# 回复评论
xhs-mcp reply-comment --feed-id FEED_ID --xsec-token XSEC_TOKEN -c "回复内容" --comment-id COMMENT_ID

# 退出登录
xhs-mcp logout

# 启动 MCP 服务
xhs-mcp serve

MCP 工具列表

API 参考

💡 提示： 点击下方功能标题可展开查看详细说明

# 浏览器扫码登录
xhs-mcp login-browser

# 终端二维码登录，在 Claude Code、Open Code 中推荐使用这种
xhs-mcp login-qrcode --terminal

# 检查登录状态
xhs-mcp status

# 退出登录
xhs-mcp logout

xhs-mcp publish -t "标题" -c "文字正文内容" -i image1.jpg -i image2.jpg --tag 旅行 --tag 美食

xhs-mcp publish-video -t "标题" -c "文字正文内容" -v video.mp4

xhs-mcp publish-text-card -c "封面文字" -p "第一页" -p "第二页" -s "基础" -t "笔记标题"

xhs-mcp search -k "关键词"

开发

# 克隆项目
git clone https://github.com/luweizheng/xhs-mcp-py.git
cd xhs-mcp-py

# 安装开发依赖
pip install -e ".[dev]"

# 安装浏览器
playwright install chromium

# 运行测试
pytest

注意事项

• 首次使用需要扫码登录，登录后 cookies 会保存到本地
• 浏览器扫码登录需要弹出浏览器窗口，请使用 xhs-mcp login-browser
• cookies 默认保存在当前目录的 cookies.json 文件
• 可通过环境变量 COOKIES_PATH 指定 cookies 文件路径

License

MIT