xhs-mcp

简体中文 | English

xhs-mcp 提供统一的命令行入口 xhs-mcp，并内置 MCP 服务器子命令。用于小红书（xiaohongshu.com）的 Model Context Protocol（MCP）服务器与 CLI 工具，支持登录、发布、搜索、推荐等自动化能力（基于 Puppeteer）。

📦 NPM 信息

• 包名: xhs-mcp

• 运行 CLI（推荐）: npx xhs-mcp <subcommand>

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

✨ 功能

• 认证：登录、登出、状态检查

• 发布：图文和视频发布

  • 图文发布：标题≤20字符（40显示单位）、内容≤1000、最多18图

  • 视频发布：支持 MP4、MOV、AVI、MKV、WebM、FLV、WMV 格式

  • ⭐ 新功能: 支持图片 URL 自动下载（HTTP/HTTPS）

  • ⭐ 新功能: 标题宽度精确验证（CJK字符2单位，ASCII字符1单位）

  • 支持本地图片路径

  • 支持 URL 和本地路径混合使用

  • 智能缓存机制，避免重复下载

• 发现：推荐、搜索、详情、评论

• 自动化：Puppeteer 驱动、无头模式、Cookie 管理

📋 可用工具

• 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和本地路径混合

🚀 快速开始（MCP）

Stdio 模式（默认）

首次运行提示：如果未安装 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 连接：

HTTP 模式

HTTP 服务器支持：

• Streamable HTTP (协议版本 2025-03-26) - 端点：/mcp

• SSE (协议版本 2024-11-05) - 端点：/sse 和 /messages

• 健康检查 - 端点：/health

详细文档请参考：HTTP Transports

🧰 CLI 子命令

🔧 客户端接入（Cursor）

Stdio 模式

.cursor/mcp.json：

HTTP 模式

.cursor/mcp.json：

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

⚠️ 注意事项

• 图文发布：标题≤20、内容≤1000、图片≤18

• 视频发布：支持多种格式，文件大小建议≤500MB

• 避免同账号多端同时网页登录

• 合理控制发帖频率

• 图片 URL 自动下载到 ./temp_images/ 目录（自动缓存）

• 图片 URL 支持格式：JPEG、PNG、GIF、WebP、BMP

📖 文档和示例

📚 文档

• 完整使用指南 - 详细的使用说明和最佳实践

• HTTP 传输文档 - HTTP/SSE 模式配置

• 发布指南 - NPM 发布流程

🎨 示例

• 使用示例 - 图片和发布示例

• 示例图片 - 可用于测试的示例图片

🧪 测试

• 运行测试 - 测试说明和用法

• 运行所有测试：npm test

🛠️ 构建说明

• 统一使用单一生产构建配置：config/webpack.config.js

• 已移除开发与优化变体；开发请直接运行：

  • npm run dev（直接运行 TypeScript CLI）

  • npm run build（打包到 dist/xhs-mcp.js）

🙏 致谢

基于 xiaohongshu-mcp 重构与扩展（TypeScript、Puppeteer、MCP 优化、日志清理、NPM 发布）。