🌸 xiaohongshu-mcp-node

基于 Model Context Protocol 的小红书自动化工具 - 让 AI 助手轻松操作小红书

xiaohongshu-mcp-node 是 xiaohongshu-mcp 的 Node.js/TypeScript 重写版本，提供了更现代化的开发体验和更强大的浏览器自动化能力。

✨ 核心特性

• 🎯 完整的 MCP 协议支持 - 13 个精心设计的工具，与 Claude Desktop、Cline 等 AI 客户端无缝集成
• 🚀 现代化技术栈 - TypeScript + Playwright + Zod，类型安全、开发高效
• 🔐 安全的登录机制 - 官方二维码登录，Cookie 自动持久化
• 📝 强大的发布能力 - 支持图文/视频发布、多图上传、标签管理、定时发布、原创声明
• 🔍 智能内容获取 - 搜索、筛选、详情抓取、评论加载，一应俱全
• 💬 完善的互动功能 - 评论、回复、点赞、收藏，全方位互动支持
• 🛠️ 开发者友好 - 清晰的分层架构、完整的类型定义、详细的日志输出

🚀 快速开始

📦 安装

# 克隆项目
git clone https://github.com/yourusername/xiaohongshu-mcp-node.git
cd xiaohongshu-mcp-node

# 安装依赖
npm install

# 安装 Playwright 浏览器
npx playwright install chromium

🔑 首次登录

在使用任何功能前，需要先登录小红书账号：

npm run login

这将打开浏览器窗口，显示小红书登录二维码。使用小红书 App 扫码登录后，Cookie 会自动保存到本地，后续操作无需重复登录。

▶️ 运行服务

# 开发模式（支持热重载）
npm run dev

# 生产模式
npm run build
npm start

📁 项目结构

xiaohongshu-mcp-node/
├── src/
│   ├── config/              # 📋 配置管理
│   │   ├── schema.ts            # Zod 配置模式定义
│   │   └── index.ts             # 配置加载器
│   ├── services/            # 🔧 业务服务层
│   │   ├── browser.service.ts   # Playwright 浏览器管理
│   │   ├── cookie.service.ts    # Cookie 持久化
│   │   └── xiaohongshu.service.ts # 业务逻辑封装
│   ├── actions/             # 🎬 小红书操作层
│   │   ├── login.action.ts      # 登录操作
│   │   ├── publish.action.ts    # 图文发布
│   │   ├── publish-video.action.ts # 视频发布
│   │   ├── search.action.ts     # 搜索功能
│   │   ├── feed-detail.action.ts # 内容详情
│   │   ├── comment.action.ts    # 评论功能
│   │   └── interaction.action.ts # 互动操作
│   ├── mcp/                 # 🔌 MCP 协议层
│   │   ├── server.ts            # MCP Server 实现
│   │   └── tools/               # 工具定义
│   ├── utils/               # 🛠️ 工具函数
│   │   ├── logger.ts            # Pino 日志系统
│   │   ├── image-processor.ts   # 图片处理
│   │   ├── title-validator.ts   # 标题验证
│   │   └── wait-helper.ts       # 等待辅助
│   ├── types/               # 📝 TypeScript 类型定义
│   └── index.ts             # 🚪 主入口
├── scripts/
│   └── login.ts             # 登录脚本
├── examples/                # 💡 使用示例
│   ├── publish-image.ts
│   └── search.ts
└── package.json

⚙️ 配置说明

环境变量

复制 .env.example 为 .env 并根据需要修改：

cp .env.example .env

| 配置项 | 说明 | 默认值 | 必填 | |--------|------|--------|------| | PORT | 服务端口 | 18060 | ❌ | | HOST | 服务地址 | 0.0.0.0 | ❌ | | HEADLESS | 无头模式 | true | ❌ | | BROWSER_BIN_PATH | 浏览器路径 | 自动检测 | ❌ | | XHS_PROXY | 代理服务器 | - | ❌ | | COOKIES_PATH | Cookie 文件路径 | ./cookies.json | ❌ | | LOG_LEVEL | 日志级别 | info | ❌ | | PAGE_TIMEOUT | 页面超时（毫秒） | 300000 | ❌ | | UPLOAD_TIMEOUT | 上传超时（毫秒） | 60000 | ❌ |

📝 功能特性

✅ 已实现功能

登录管理

• ✅ 登录状态检查
• ✅ 二维码登录
• ✅ Cookie 管理

内容发布

• ✅ 发布图文内容（支持多图、标签、定时发布、原创声明）
• ✅ 发布视频内容（支持标签、定时发布）
• ✅ 图片自动下载（支持 URL）
• ✅ 标题验证（20字限制）

内容获取

• ✅ 搜索内容（支持筛选）
• ✅ 获取推荐列表
• ✅ 获取内容详情
• ✅ 加载评论

互动功能

• ✅ 发表评论
• ✅ 回复评论
• ✅ 点赞/取消点赞
• ✅ 收藏/取消收藏

MCP 协议

• ✅ 完整的 MCP Server 实现
• ✅ 13 个 MCP 工具
• ✅ 与 AI 客户端集成（Claude Desktop、Cline 等）

🔌 MCP 集成指南

与 Claude Desktop 集成

1. 构建项目

   npm run build

2. 配置 Claude Desktop

   编辑配置文件（根据操作系统选择）：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "xiaohongshu": {
         "command": "node",
         "args": ["/absolute/path/to/xiaohongshu-mcp-node/dist/index.js"],
         "env": {
           "HEADLESS": "true",
           "COOKIES_PATH": "/absolute/path/to/cookies.json"
         }
       }
     }
   }

3. 重启 Claude Desktop

   配置完成后，重启 Claude Desktop 即可在对话中使用小红书功能。

📚 可用的 MCP 工具

| 工具名称 | 功能描述 | 主要参数 | |---------|---------|---------| | check_login_status | 检查登录状态 | - | | get_login_qrcode | 获取登录二维码 | - | | delete_cookies | 删除 cookies | - | | publish_content | 发布图文内容 | title, content, images, tags | | publish_video | 发布视频内容 | title, content, video, tags | | search_feeds | 搜索内容 | keyword, filters | | list_feeds | 获取推荐列表 | - | | get_feed_detail | 获取内容详情 | feedId, xsecToken | | post_comment | 发表评论 | feedId, xsecToken, content | | reply_comment | 回复评论 | feedId, xsecToken, commentId, content | | like_feed | 点赞/取消点赞 | feedId, xsecToken, unlike | | favorite_feed | 收藏/取消收藏 | feedId, xsecToken, unfavorite |

💡 使用示例

在 Claude Desktop 中，你可以这样使用：

帮我发布一篇小红书笔记，标题是"Node.js 开发技巧"，
内容是"分享一些实用的 Node.js 开发经验..."，
使用这三张图片：[图片路径]，添加标签：Node.js、编程、技术分享

Claude 会自动调用 publish_content 工具完成发布。

�️ 开发

# 开发模式
npm run dev

# 类型检查
npm run build

# 代码格式化
npm run format

# 代码检查
npm run lint

📂 项目架构

src/
├── config/              # 配置管理（Zod 验证）
├── services/            # 业务服务层
│   ├── browser.service.ts    # 浏览器管理（Playwright）
│   ├── cookie.service.ts     # Cookie 持久化
│   └── xiaohongshu.service.ts # 业务逻辑封装
├── actions/             # 小红书操作层
│   ├── login.action.ts       # 登录操作
│   ├── publish.action.ts     # 发布图文
│   ├── publish-video.action.ts # 发布视频
│   ├── search.action.ts      # 搜索
│   ├── feed-detail.action.ts # 详情
│   ├── comment.action.ts     # 评论
│   └── interaction.action.ts # 互动
├── mcp/                 # MCP 协议层
│   ├── server.ts            # MCP Server
│   └── tools/               # 工具定义
├── utils/               # 工具函数
│   ├── logger.ts            # 日志（Pino）
│   ├── image-processor.ts   # 图片处理
│   ├── title-validator.ts   # 标题验证
│   └── wait-helper.ts       # 等待辅助
└── types/               # TypeScript 类型定义

🎯 为什么选择 Node.js 版本？

相比 Go 原版，Node.js 版本提供了：

• ✅ 更快的开发迭代 - TypeScript 热重载，无需编译等待
• ✅ 更成熟的浏览器自动化 - Playwright 生态完善，文档丰富
• ✅ 更好的调试体验 - Chrome DevTools 原生支持
• ✅ 更丰富的生态系统 - npm 海量包，开箱即用
• ✅ 更低的学习曲线 - JavaScript/TypeScript 开发者友好

🤝 贡献

欢迎提交 Issue 和 Pull Request！

在提交 PR 前，请确保：

• 代码通过 ESLint 检查：npm run lint
• 代码格式符合规范：npm run format
• TypeScript 编译无错误：npm run build

📄 开源协议

本项目采用 Apache-2.0 协议开源。

🙏 致谢与声明

致谢

本项目是 xiaohongshu-mcp 的 Node.js/TypeScript 重写版本。

特别感谢：

• xpzouying - 原项目作者，提供了优秀的设计思路
• Anthropic - Model Context Protocol 的创建者
• Playwright - 强大的浏览器自动化框架

免责声明

本项目仅供学习和研究使用，请勿用于任何商业用途或违反小红书服务条款的行为。使用本工具产生的任何后果由使用者自行承担。

如果这个项目对你有帮助，请给它一个 ⭐️ Star！

Made with ❤️ by the community