xpzouying/xiaohongshu-mcp

xiaohongshu-mcp

MCP for 小红书 / xiaohongshu.com。让你的 AI 助手直接访问小红书数据。

🚀 快速开始：选择最适合你的版本

[!IMPORTANT]

#### 🔥 方案 A：Openclaw 深度集成 (推荐给开发者)

- Openclaw 太火啦 🔥🔥🔥 ，新增 Openclaw 支持，分为两种，请各位按需使用：

- xiaohongshu-mcp-skills（适用于已部署完本项目的用户）

- xiaohongshu-skills（开箱即用版）

[!TIP]

#### ✨ 方案 B：x-mcp 浏览器插件版 (推荐给非技术同学 / 追求极简的用户)

- 不想折腾 Docker 或部署环境？试试：xpzouying/x-mcp

- 零配置：安装插件即用，无需任何代码、代理或复杂的环境配置。

- 安全稳定：直接在常用浏览器 (Chrome/Edge) 及本地网络运行，无服务器 IP 风险，且能解决 90% 的部署报错。

📖 相关资源

• 我的博客文章：haha.ai/xiaohongshu-mcp
• 贡献指南：Contributing Guide

🛠️ 疑难杂症

如果您在部署传统 Docker 版本时遇到问题，务必先查看：各种疑难杂症 (Issues #56)。

提示：如果环境排查太耗时，切换到 x-mcp 插件版 通常是更高效的选择。

Star History

赞赏支持

本项目所有的赞赏都会用于慈善捐赠。所有的慈善捐赠记录，请参考 DONATIONS.md。

捐赠时，请备注 MCP 以及名字。 如需更正/撤回署名，请开 Issue 或通过邮箱联系。

支付宝（不展示二维码）：

通过支付宝向 xpzouying@gmail.com 赞赏。

微信：

项目简介

主要功能

💡 提示： 点击下方功能标题可展开查看视频演示

   ["https://example.com/image1.jpg", "https://example.com/image2.png"]
   

   ["/Users/username/Pictures/image1.jpg", "/home/user/images/image2.png"]
   

"/Users/username/Videos/video.mp4"

小红书基础运营知识

• 标题：（非常重要）小红书要求标题不超过 20 个字
• 正文：（非常重要）：正文不能超过 1000 个字
• 当前支持图文发送以及视频发送：从推荐的角度看，图文的流量会比视频以及纯文字的更好。
• （低优先级）可以考虑纯文字的支持。1. 个人感觉纯文字会大大增加运营的复杂度；2. 纯文字在我的使用场景的价值较低。
• Tags：现已支持。添加合适的 Tags 能带来更多的流量。
• 根据本人实操，小红书每天的发帖量应该是 50 篇。
• （非常重要）小红书的同一个账号不允许在多个网页端登录，如果你登录了当前 xiaohongshu-mcp 后，就不要再在其他的网页端登录该账号，否则就会把当前 MCP 的账号“踢出登录”。你可以使用移动 App 端进行查看当前账号信息。
• 曝光低的话，首先查看内容中是否有违禁词，搜一下有很多第三方免费工具。
• 一定不要出现引流、纯搬运的情况，属于官方重点打击对象。

1. 该项目是在自己的另外一个项目的基础上开源出来的，原来的项目稳定运行一年多，没有出现过封号的情况，只有出现过 Cookies 过期需要重新登录。 2. 我是使用 Claude Code 接入，稳定自动化运营数周后，验证没有问题后开源。 3. 如果账号没有实名认证，特别是新号，一般会触发 实名认证 的消息提醒（参见下图）。⚠️ 这个不是封号，不用 MCP 也会要求实名认证。实名认证后，账号就正常了。建议使用该项目前就先实名。

该项目是基于学习的目的，禁止一切违法行为。

实操结果

第一天点赞/收藏数达到了 999+，

一周左右的成果

1. 使用教程

1.1. 快速开始（推荐）

方式一：下载预编译二进制文件

直接从 GitHub Releases 下载对应平台的二进制文件：

主程序（MCP 服务）：

• macOS Apple Silicon: xiaohongshu-mcp-darwin-arm64
• Windows x64: xiaohongshu-mcp-windows-amd64.exe
• Linux x64: xiaohongshu-mcp-linux-amd64

• macOS Apple Silicon: xiaohongshu-login-darwin-arm64
• Windows x64: xiaohongshu-login-windows-amd64.exe
• Linux x64: xiaohongshu-login-linux-amd64

目前支持以上三个平台。macOS Intel 与 Linux ARM64 暂不支持。

使用步骤：

# 1. 首先运行登录工具
chmod +x xiaohongshu-login-darwin-arm64
./xiaohongshu-login-darwin-arm64
2. 然后启动 MCP 服务
chmod +x xiaohongshu-mcp-darwin-arm64
./xiaohongshu-mcp-darwin-arm64

⚠️ 重要提示：首次运行时会自动下载无头浏览器（约 150MB），请确保网络连接正常。后续运行无需重复下载。

方式二：源码编译

# 配置 GOPROXY 环境变量，以下三选一
1. 七牛 CDN
go env -w  GOPROXY=https://goproxy.cn,direct
2. 阿里云
go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/,direct
3. 官方
go env -w  GOPROXY=https://goproxy.io,direct

方式三：使用 Docker 容器

默认推荐无界面版；需要查看浏览器或短暂人工辅助时，选择 GUI 版。

| 部署方式 | 适用场景 | 镜像标签 | | --- | --- | --- | | 无界面（默认） | 日常 MCP 自动化，镜像更小 | latest、vX.Y.Z | | GUI（noVNC，可选） | 查看登录页面、排查现场、辅助输入或选择素材 | novnc、vX.Y.Z-novnc |

在项目根目录执行，二选一：

# 默认无界面版
docker compose -f docker/docker-compose.yml up -d

# 可选 GUI 版
docker compose -f docker/novnc/compose.yml up -d

GUI 启动后打开 浏览器桌面。两种部署的 MCP 地址均为 http://127.0.0.1:18060/mcp。

GUI 无独立密码，仅限本机或 SSH 转发访问，不要直接暴露公网。切换部署前先停止旧实例。

详细步骤、镜像源和数据目录配置见 Docker 部署指南 与 GUI 部署指南。

Windows 遇到问题首先看这里：Windows 安装指南

1.2. 登录

第一次需要手动登录，需要保存小红书的登录状态。

使用二进制文件：

# 运行对应平台的登录工具
./xiaohongshu-login-darwin-arm64

使用源码：

go run cmd/login/main.go

1.3. 启动 MCP 服务

启动 xiaohongshu-mcp 服务。

使用二进制文件：

# 默认：无头模式，没有浏览器界面
./xiaohongshu-mcp-darwin-arm64
非无头模式，有浏览器界面
./xiaohongshu-mcp-darwin-arm64 -headless=false

使用源码：

# 默认：无头模式，没有浏览器界面
go run .
非无头模式，有浏览器界面
go run . -headless=false

配置代理（可选）：

如果需要通过代理访问，可以设置 XHS_PROXY 环境变量：

# 设置代理后启动
XHS_PROXY=http://user:pass@proxy:port ./xiaohongshu-mcp-darwin-arm64
或使用源码
XHS_PROXY=http://proxy:port go run .

支持 HTTP/HTTPS/SOCKS5 代理，日志中会自动隐藏代理的认证信息。

访问鉴权（可选）：

默认关闭鉴权。生产环境建议使用 AUTH_TOKEN 环境变量配置；非空的启动参数优先于环境变量，留空则读取 AUTH_TOKEN。

# 环境变量
AUTH_TOKEN=your-secret-token ./xiaohongshu-mcp-darwin-arm64
AUTH_TOKEN=your-secret-token go run .
非空启动参数（优先于环境变量）
./xiaohongshu-mcp-darwin-arm64 -token=your-secret-token
go run . -token=your-secret-token

启用鉴权后，所有 MCP 客户端都必须配置自定义请求头 Authorization: Bearer 。命令行参数可能被进程列表看到，部署环境优先使用 AUTH_TOKEN。

例如，支持自定义请求头的 MCP 客户端可使用以下配置：

{
  "mcpServers": {
    "xiaohongshu-mcp": {
      "url": "http://localhost:18060/mcp",
      "headers": { "Authorization": "Bearer your-secret-token" }
    }
  }
}

1.4. 验证 MCP

npx @modelcontextprotocol/inspector

运行后，打开红色标记的链接，配置 MCP inspector，输入 http://localhost:18060/mcp ，点击 Connect 按钮。

注意： 左侧边框中的选项是否正确。

按照上面配置 MCP inspector 后，点击 List Tools 按钮，查看所有的 Tools。

1.5. 使用 MCP 发布

检查登录状态

发布图文

示例中是从 https://unsplash.com/ 中随机找了个图片做测试。

搜索内容

使用搜索功能，根据关键词搜索小红书内容：

2. MCP 客户端接入

本服务支持标准的 Model Context Protocol (MCP)，可以接入各种支持 MCP 的 AI 客户端。

2.1. 快速开始

启动 MCP 服务

# 启动服务（默认无头模式）
go run .
或者有界面模式
go run . -headless=false

服务将运行在：http://localhost:18060/mcp

验证服务状态

# 测试 MCP 连接
curl -X POST http://localhost:18060/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

Claude Code CLI 接入

# 添加 HTTP MCP 服务器
claude mcp add --transport http xiaohongshu-mcp http://localhost:18060/mcp
检查 MCP 是否添加成功（确保 MCP 已经启动的前提下，运行下面命令）
claude mcp list

2.2. 支持的客户端

# 添加 HTTP MCP 服务器
claude mcp add --transport http xiaohongshu-mcp http://localhost:18060/mcp
检查 MCP 是否添加成功（确保 MCP 已经启动的前提下，运行下面命令）
claude mcp list

opencode mcp add

┌  Add MCP server
│
◇  Enter MCP server name
│  xiaohongshu-mcp
│
◇  Select MCP server type
│  Remote
│
◇  Enter MCP server URL
│  http://localhost:18060/mcp
│
◇  Does this server require OAuth authentication?
│  No
│
◆  MCP server "xiaohongshu-mcp" added to C:\Users\admin\.config\opencode\opencode.json
│
└  MCP server added successfully

opencode mcp list

┌  MCP Servers
│
●  ✓ xiaohongshu-mcp connected

Cursor

配置文件的方式

创建或编辑 MCP 配置文件：

项目级配置（推荐）： 在项目根目录创建 .cursor/mcp.json：

{
  "mcpServers": {
    "xiaohongshu-mcp": {
      "url": "http://localhost:18060/mcp",
      "description": "小红书内容发布服务 - MCP Streamable HTTP"
    }
  }
}

全局配置： 在用户目录创建 ~/.cursor/mcp.json (同样内容)。

使用步骤

1. 确保小红书 MCP 服务正在运行 2. 保存配置文件后，重启 Cursor 3. 在 Cursor 聊天中，工具应该自动可用 4. 可以通过聊天界面的 "Available Tools" 查看已连接的 MCP 工具

Demo

插件 MCP 接入：

调用 MCP 工具：（以检查登录状态为例）

VSCode

方法一：使用命令面板配置

1. 按 Ctrl/Cmd + Shift + P 打开命令面板 2. 运行 MCP: Add Server 命令 3. 选择 HTTP 方式。 4. 输入地址： http://localhost:18060/mcp，或者修改成对应的 Server 地址。 5. 输入 MCP 名字： xiaohongshu-mcp。

方法二：直接编辑配置文件

工作区配置（推荐）： 在项目根目录创建 .vscode/mcp.json：

{
  "servers": {
    "xiaohongshu-mcp": {
      "url": "http://localhost:18060/mcp",
      "type": "http"
    }
  },
  "inputs": []
}

查看配置：

1. 确认运行状态。 2. 查看 tools 是否正确检测。

Demo

以搜索帖子内容为例：

{
  "mcpServers": {
    "xiaohongshu": {
      "httpUrl": "http://localhost:18060/mcp",
      "timeout": 30000
    }
  }
}

# 启动 MCP Inspector
npx @modelcontextprotocol/inspector
在浏览器中连接到：http://localhost:18060/mcp

{
  "xiaohongshu-mcp": {
    "url": "http://localhost:18060/mcp",
    "type": "streamableHttp",
    "autoApprove": [],
    "disabled": false
  }
}

帮我检查小红书登录状态

帮我发布一篇关于春天的图文到小红书，使用这张图片：/path/to/spring.jpg

搜索小红书上关于"美食"的内容

npm i -g mcporter
npx mcporter config add xiaohongshu-mcp http://localhost:18060/mcp
npx mcporter list xiaohongshu-mcp

{
  "name": "xiaohongshu-mcp",
  "url": "http://localhost:18060/mcp",
  "type": "http"
}

2.3. 可用 MCP 工具

连接成功后，可使用以下 MCP 工具：

• check_login_status - 检查小红书登录状态（无参数）
• get_login_qrcode - 获取登录二维码，返回 Base64 图片和超时时间（无参数）
• delete_cookies - 删除 cookies 文件，重置登录状态，删除后需要重新登录（无参数）
• publish_content - 发布图文内容到小红书（必需：title, content, images）
• images: 图片路径列表（至少1张），支持 HTTP 链接或本地绝对路径，推荐使用本地路径
• tags: 话题标签列表（可选），如 ["美食", "旅行", "生活"]
• schedule_at: 定时发布时间（可选），ISO8601 格式，支持 1 小时至 14 天内
• is_original: 是否声明原创（可选），默认不声明
• visibility: 可见范围（可选），支持 公开可见（默认）、仅自己可见、仅互关好友可见
• products: 商品关键词列表（可选），用于绑定带货商品。填写商品名称或商品ID，系统会自动搜索并选择第一个匹配结果。需账号已开通商品功能。示例: [面膜, 防晒霜SPF50]
• publish_with_video - 发布视频内容到小红书（必需：title, content, video）
• video: 本地视频文件绝对路径（仅支持单个视频文件）
• tags: 话题标签列表（可选），如 ["美食", "旅行", "生活"]
• schedule_at: 定时发布时间（可选），ISO8601 格式，支持 1 小时至 14 天内
• visibility: 可见范围（可选），支持 公开可见（默认）、仅自己可见、仅互关好友可见
• products: 商品关键词列表（可选），用于绑定带货商品。填写商品名称或商品ID，系统会自动搜索并选择第一个匹配结果。需账号已开通商品功能。示例: [面膜, 防晒霜SPF50]
• list_feeds - 获取小红书首页推荐列表（无参数）
• search_feeds - 搜索小红书内容（必需：keyword）
• filters: 筛选选项（可选）
• sort_by: 排序依据 - 综合（默认）| 最新 | 最多点赞 | 最多评论 | 最多收藏
• note_type: 笔记类型 - 不限（默认）| 视频 | 图文
• publish_time: 发布时间 - 不限（默认）| 一天内 | 一周内 | 半年内
• search_scope: 搜索范围 - 不限（默认）| 已看过 | 未看过 | 已关注
• location: 位置距离 - 不限（默认）| 同城 | 附近
• get_feed_detail - 获取帖子详情，包括互动数据和评论（必需：feed_id, xsec_token）
• load_all_comments: 是否加载全部评论（可选），默认 false 仅返回前 10 条一级评论
• limit: 限制加载的一级评论数量（可选），仅当 load_all_comments=true 时生效，默认 20
• click_more_replies: 是否展开二级回复（可选），仅当 load_all_comments=true 时生效，默认 false
• reply_limit: 跳过回复数过多的评论（可选），仅当 click_more_replies=true 时生效，默认 10
• scroll_speed: 滚动速度（可选），slow | normal | fast，仅当 load_all_comments=true 时生效
• post_comment_to_feed - 发表评论到小红书帖子（必需：feed_id, xsec_token, content）
• reply_comment_in_feed - 回复笔记下的指定评论（必需：feed_id, xsec_token, content，以及 comment_id 或 user_id 至少一个）
• like_feed - 点赞/取消点赞（必需：feed_id, xsec_token）
• unlike: 是否取消点赞（可选），true 为取消点赞，默认为点赞
• favorite_feed - 收藏/取消收藏（必需：feed_id, xsec_token）
• unfavorite: 是否取消收藏（可选），true 为取消收藏，默认为收藏
• user_profile - 获取用户个人主页信息（必需：user_id, xsec_token）

2.4. 使用示例

使用 Claude Code 发布内容到小红书：

示例 1：使用 HTTP 图片链接

帮我写一篇帖子发布到小红书上，
配图为：https://cn.bing.com/th?id=OHR.MaoriRock_EN-US6499689741_UHD.jpg&w=3840
图片是："纽西兰陶波湖的Ngātoroirangi矿湾毛利岩雕（© Joppi/Getty Images）"
使用 xiaohongshu-mcp 进行发布。

示例 2：使用本地图片路径（推荐）

帮我写一篇关于春天的帖子发布到小红书上，
使用这些本地图片：
/Users/username/Pictures/spring_flowers.jpg
/Users/username/Pictures/cherry_blossom.jpg

使用 xiaohongshu-mcp 进行发布。

示例 3：发布视频内容

帮我写一篇关于美食制作的视频发布到小红书上，
使用这个本地视频文件：
/Users/username/Videos/cooking_tutorial.mp4

使用 xiaohongshu-mcp 的视频发布功能。

发布结果：

2.5. 💬 MCP 使用常见问题解答

---

⚠️ 以下是使用 OpenClaw + MCPorter 时的已知风险，使用前请充分了解：

• OpenClaw 的 AI 自动部署行为不在本项目的维护范围内，部署结果无法保证
• MCPorter 作为中间层可能引入额外的兼容性问题，与 xiaohongshu-mcp 本身无关
• 若遇到连接失败、工具调用异常等问题，请先排查 MCPorter 自身的配置，而非提交 Issue
• 在提问社区或群组前，请先确认问题是否能在不使用 OpenClaw 的情况下复现

---

Q: 为什么检查登录用户名显示 xiaghgngshu-mcp？ A: 用户名是写死的。

---

Q: 显示发布成功后，但实际上没有显示？ A: 排查步骤如下：

1. 使用 非无头模式 重新发布一次。 2. 更换 不同的内容 重新发布。 3. 登录网页版小红书，查看账号是否被 风控限制网页版发布。 4. 检查 图片大小 是否过大。 5. 确认 图片路径中没有中文字符。 6. 若使用网络图片地址，请确认 图片链接可正常访问。

---

Q: 在设备上运行 MCP 程序出现闪退如何解决？ A:

1. 建议 从源码安装。 2. 或使用 Docker 安装 xiaohongshu-mcp，教程参考：

• 使用 Docker 安装 xiaohongshu-mcp
• X-MCP 项目页面

Q: 使用 http://localhost:18060/mcp 进行 MCP 验证时提示无法连接？ A:

• 在 Docker 环境 下，请使用

• 在 非 Docker 环境 下，请使用 本机 IPv4 地址 访问。

3. 🌟 实战案例展示 (Community Showcases)

💡 强烈推荐查看：这些都是社区贡献者的真实使用案例，包含详细的配置步骤和实战经验！

📚 完整教程列表

1. n8n 完整集成教程 - 工作流自动化平台集成 2. Cherry Studio 完整配置教程 - AI 客户端完美接入 3. Claude Code + Kimi K2 接入教程 - Claude Code 门槛太高，那么就接入 Kimi 国产大模型吧～ 4. AnythingLLM 完整指南 - AnythingLLM 是一款 all-in-one 多模态 AI 客户端，支持 workflow 定义，支持多种大模型和插件扩展。

🎯 提示: 点击上方链接查看详细的图文教程，快速上手各种集成方案！

> 📢 欢迎贡献: 如果你有新的集成案例，欢迎提交 PR 分享给社区！

4. 小红书 MCP 互助群

重要：在群里问问题之前，请一定要先仔细看完 README 文档以及查看 Issues。

微信群

飞书群

| 飞书 2 群 | 飞书 3 群 | 飞书 4 群 | 飞书 5 群 | | :-----------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------: | | | | | |

注意：

> 1. 微信群的二维码有时间限制，有时候忘记更新，麻烦等待更新或者提交 Issue 催我更新。

2. 飞书群，如果有的群满了，可以尝试扫一下另外一个群，总有坑位。

🙏 致谢贡献者 ✨

感谢以下所有为本项目做出贡献的朋友！（排名不分先后）

zy 💻 🤔 📖 🎨 🚧 🚇 👀

clearwater GitHub Stars & Activity 16,760Stars 2,461Forks 113Open issues GoLanguage GitHub Popularity GitHub stars16,760 Forks2,461 Open issues113 Primary languageGo LicenseApache-2.0 Stars gained today37 Created2025-08-03 Last pushed2026-11-02 Trending History Daily boardrank #39 · ▲ 37 stars Related AI Projects 1 ollama / ollama Go★ 185,698⑂ 18,873▲ 143 stars → 2 JuliusBrussee / caveman Go★ 116,900⑂ 0 → 3 netbirdio / netbird Go★ 30,565⑂ 1,819▲ 56 stars → 4 gastownhall / beads Go★ 28,425⑂ 1,918▲ 42 stars → 5 egoist / kero Go★ 1,367⑂ 130▲ 17 stars → 6 Mag1cFall / AIStudio2API Go★ 677⑂ 152▲ 35 stars → 7 Balanov / uncut Go★ 570⑂ 4 → 8 morluto / rea TypeScript★ 422,302⑂ 0 → More AI Rankings View AI Trending Today View AI Trending This Week See AI Trending This Month Browse AI Image Projects Browse AI Video Projects Browse AI Audio Projects Browse AI Model & LLM Tools Browse AI Agent Skills