xhs-mcp

🚀 xhs-mcp

xhs-mcp 是一款针对小红书（xiaohongshu.com）的工具，它提供了统一的命令行入口 xhs-mcp，并内置 MCP 服务器子命令。借助 Puppeteer，该工具支持登录、发布、搜索、推荐等自动化操作，为用户在小红书上的运营提供了便利。

简体中文 | English

🚀 快速开始

MCP 启动

Stdio 模式（默认）

npx xhs-mcp mcp

# 调试日志
XHS_ENABLE_LOGGING=true npx xhs-mcp mcp

⚠️ 重要提示

首次运行时，如果未安装 Puppeteer 浏览器，需先执行：

npx xhs-mcp browser    # 自动检查并安装 Chromium，显示可执行路径
# 或
npx puppeteer browsers install chrome

输出示例：

{
  "success": true,
  "message": "Chromium is ready",
  "data": {
    "installed": true,
    "executablePath": "/path/to/chromium"
  }
}

验证 MCP 连接：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npx xhs-mcp mcp

HTTP 模式

# 启动 HTTP 服务器（默认端口 3000）
npx xhs-mcp mcp --mode http

# 指定端口
npx xhs-mcp mcp --mode http --port 8080

# 调试模式
XHS_ENABLE_LOGGING=true npx xhs-mcp mcp --mode http

HTTP 服务器支持：

• Streamable HTTP (协议版本 2025-03-26) - 端点：/mcp
• SSE (协议版本 2024-11-05) - 端点：/sse 和 /messages
• 健康检查 - 端点：/health

详细文档请参考：HTTP Transports

✨ 主要特性

• 认证功能：支持登录、登出以及状态检查操作。
• 发布功能：
  • 图文发布：标题长度≤20字符（40显示单位），内容长度≤1000，最多可上传18张图片。
  • 视频发布：支持 MP4、MOV、AVI、MKV、WebM、FLV、WMV 等格式。
  • ⭐ 新功能：支持图片 URL 自动下载（HTTP/HTTPS），并采用智能缓存机制，避免重复下载。
  • ⭐ 新功能：标题宽度精确验证（CJK字符2单位，ASCII字符1单位）。
  • 支持本地图片路径，也支持 URL 和本地路径混合使用。
• 发现功能：可进行推荐、搜索、查看详情以及评论等操作。
• 自动化能力：由 Puppeteer 驱动，支持无头模式和 Cookie 管理。

📦 安装指南

NPM 信息

• 包名: xhs-mcp
• 运行 CLI（推荐）: npx xhs-mcp <subcommand>
• 启动 MCP：npx xhs-mcp mcp [--mode stdio|http] [--port 3000]

💻 使用示例

可用工具

• xhs_auth_login、xhs_auth_logout、xhs_auth_status
• xhs_discover_feeds、xhs_search_note、xhs_get_note_detail
• xhs_comment_on_note
• xhs_publish_content（统一发布接口：type、title、content、media_paths、tags）
  • 图片发布：可传入1 - 18个图片文件或URL。
  • 视频发布：需传入恰好1个视频文件。
  • 混合使用：支持图片URL和本地路径混合。

CLI 子命令示例

# 认证
npx xhs-mcp login --timeout 120
npx xhs-mcp logout
npx xhs-mcp status

# 浏览器依赖
npx xhs-mcp browser [--with-deps]  # 检查并安装 Chromium，显示可执行路径

# 发现与检索
npx xhs-mcp feeds [-b /path/to/chromium]
npx xhs-mcp search -k 关键字 [-b /path/to/chromium]
npx xhs-mcp note-detail --feed-id <id> --xsec-token <token> [-b /path/to/chromium]

# 互动
npx xhs-mcp comment --feed-id <id> --xsec-token <token> -n "Nice!" [-b /path/to/chromium]

# 发布
# 使用本地图片
npx xhs-mcp publish --type image --title 标题 --content 内容 -m path1.jpg,path2.png --tags a,b [-b /path/to/chromium]

# ⭐ 使用图片 URL（自动下载）
npx xhs-mcp publish --type image --title 标题 --content 内容 -m "https://example.com/img1.jpg,https://example.com/img2.png" --tags a,b

# 混合使用 URL 和本地路径
npx xhs-mcp publish --type image --title 标题 --content 内容 -m "https://example.com/img1.jpg,./local/img2.jpg" --tags a,b

# 发布视频
npx xhs-mcp publish --type video --title 视频标题 --content 视频描述 -m path/to/video.mp4 --tags a,b [-b /path/to/chromium]

# 查看可用工具
npx xhs-mcp tools [--detailed] [--json]

# 启动 MCP
npx xhs-mcp mcp [--mode stdio|http] [--port 3000]

客户端接入（Cursor）

Stdio 模式

.cursor/mcp.json：

{
  "mcpServers": {
    "xhs-mcp": {
      "command": "npx",
      "args": ["xhs-mcp", "mcp"],
      "env": { "XHS_ENABLE_LOGGING": "true" }
    }
  }
}

HTTP 模式

.cursor/mcp.json：

{
  "mcpServers": {
    "xhs-mcp-http": {
      "command": "npx",
      "args": ["xhs-mcp", "mcp", "--mode", "http", "--port", "3000"],
      "env": { "XHS_ENABLE_LOGGING": "true" }
    }
  }
}

或者使用 HTTP 客户端直接连接：

{
  "mcpServers": {
    "xhs-mcp-http": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

🔧 技术细节

客户端接入（Cursor）

支持 Stdio 和 HTTP 两种模式接入 Cursor，通过配置 .cursor/mcp.json 文件实现。

构建说明

• 统一使用单一生产构建配置：config/webpack.config.js。
• 已移除开发与优化变体；开发请直接运行：
  • npm run dev（直接运行 TypeScript CLI）
  • npm run build（打包到 dist/xhs-mcp.js）

📄 许可证

本项目采用 MIT 许可证。

⚠️ 注意事项

⚠️ 重要提示

• 图文发布：标题长度≤20、内容长度≤1000、图片数量≤18。
• 视频发布：支持多种格式，文件大小建议≤500MB。
• 避免同账号多端同时网页登录。
• 合理控制发帖频率。
• 图片 URL 自动下载到 ./temp_images/ 目录（自动缓存）。
• 图片 URL 支持格式：JPEG、PNG、GIF、WebP、BMP。

📖 详细文档

📚 文档

• 完整使用指南 - 详细的使用说明和最佳实践。
• HTTP 传输文档 - HTTP/SSE 模式配置。
• 发布指南 - NPM 发布流程。

🎨 示例

• 使用示例 - 图片和发布示例。
• 示例图片 - 可用于测试的示例图片。

🧪 测试

• 运行测试 - 测试说明和用法。
• 运行所有测试：npm test

🙏 致谢

本项目基于 xiaohongshu-mcp 进行重构与扩展，包括 TypeScript 化、Puppeteer 集成、MCP 优化、日志清理以及 NPM 发布等方面。