xhs-mcp

XHS-MCP 使用指南

概述

本指南详细介绍如何使用 XHS-MCP 进行小红书自动化操作，包括认证、发布、搜索等功能。

🚀 快速开始

安装和运行

# 使用 npx 运行（推荐）
npx xhs-mcp --help

# 或者全局安装
npm install -g xhs-mcp
xhs-mcp --help

首次使用

检查浏览器依赖
```
npx xhs-mcp browser
```
登录账户
```
npx xhs-mcp login --timeout 120
```
验证登录状态
```
npx xhs-mcp status
```

📝 内容发布

图文发布

使用本地图片

npx xhs-mcp publish \
  --type image \
  --title "美丽的风景" \
  --content "分享一张美丽的风景照片" \
  --media-paths "./images/photo1.jpg,./images/photo2.png" \
  --tags "风景,摄影"

使用图片 URL（新功能）

npx xhs-mcp publish \
  --type image \
  --title "网络图片分享" \
  --content "来自网络的高质量图片" \
  --media-paths "https://example.com/image1.jpg,https://example.com/image2.png" \
  --tags "网络,分享"

混合使用本地和网络图片

npx xhs-mcp publish \
  --type image \
  --title "我的相册" \
  --content "本地照片和网络图片的完美结合" \
  --media-paths "https://example.com/remote.jpg,./local/photo.jpg,https://example.com/another.png" \
  --tags "相册,混合"

视频发布

npx xhs-mcp publish \
  --type video \
  --title "我的视频" \
  --content "分享一个有趣的视频" \
  --media-paths "./videos/my_video.mp4" \
  --tags "视频,分享"

支持的格式

图片格式

JPEG/JPG
PNG
GIF
WebP
BMP

视频格式

MP4
MOV
AVI
MKV
WebM
FLV
WMV

🔍 内容发现

获取推荐内容

npx xhs-mcp feeds

搜索笔记

npx xhs-mcp search -k "美食"

获取笔记详情

npx xhs-mcp note-detail --feed-id <feed_id> --xsec-token <token>

评论笔记

npx xhs-mcp comment --feed-id <feed_id> --xsec-token <token> -n "很棒的内容！"

🤖 MCP 服务器模式

Stdio 模式（默认）

# 启动 MCP 服务器
npx xhs-mcp mcp

# 启用调试日志
XHS_ENABLE_LOGGING=true 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

客户端配置

Cursor 配置

.cursor/mcp.json：

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

HTTP 客户端配置

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

🛠️ 高级功能

图片 URL 自动下载

XHS-MCP 现在支持直接使用 HTTP/HTTPS 图片 URL 进行发布，无需手动下载：

工作原理

URL 识别：自动识别以 http:// 或 https:// 开头的路径
智能下载：将 URL 图片下载到 ./temp_images/ 目录
格式验证：检查文件签名，确保是有效的图片格式
缓存机制：已下载的图片会被缓存，避免重复下载
混合处理：URL 和本地路径可以混合使用

缓存机制

使用 URL 的 SHA256 哈希值生成唯一文件名
相同的 URL 只会下载一次
缓存的图片可以在多次发布中重复使用

下载位置

默认情况下，下载的图片会保存在项目根目录的 temp_images/ 文件夹中：

xhs-mcp/
├── temp_images/          # 自动创建
│   ├── img_abc123_1234567890.jpg
│   ├── img_def456_1234567891.png
│   └── ...

错误处理

常见错误及解决方案

1. 图片下载失败

Error: Failed to download image: HTTP 404 Not Found

解决方案：检查 URL 是否正确，图片是否仍然存在

2. 无效的图片格式

Error: Downloaded file is not a valid image

解决方案：确保 URL 指向的是真实的图片文件，而不是 HTML 页面

3. 下载超时

Error: Image download timeout after 30000ms

解决方案：

检查网络连接
图片可能太大
尝试使用本地图片

4. 本地文件不存在

Error: Local image file not found: ./image.jpg

解决方案：检查文件路径是否正确

📊 性能优化

1. 使用缓存

如果需要多次发布相同的图片，第一次下载后会自动缓存：

# 第一次 - 下载图片（可能需要几秒）
npx xhs-mcp publish --media-paths "https://example.com/large-image.jpg"

# 第二次 - 使用缓存（即时）
npx xhs-mcp publish --media-paths "https://example.com/large-image.jpg"

2. 预下载图片

对于大批量发布，可以先下载图片到本地：

# 使用测试脚本下载图片
node examples/test-image-url-download.js

3. 合理控制并发

避免同时运行多个发布任务，建议串行执行。

⚠️ 注意事项

发布限制

图文发布：标题≤20字符、内容≤1000字符、图片≤18张
视频发布：文件大小建议≤500MB
频率控制：避免过于频繁的发布操作

账号安全

避免同账号多端同时网页登录
合理控制操作频率
定期检查登录状态

网络要求

确保网络连接稳定
图片 URL 需要可以公开访问
避免使用需要登录才能访问的图片

🔧 调试和故障排除

启用调试日志

XHS_ENABLE_LOGGING=true npx xhs-mcp <command>

查看下载的图片

ls -lh temp_images/

清理缓存

rm -rf temp_images/

验证 MCP 连接

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

📚 更多资源

🤝 获取帮助

查看可用工具：npx xhs-mcp tools
查看详细帮助：npx xhs-mcp <command> --help
提交问题：GitHub Issues

提示：这个功能参考了 xiaohongshu-mcp 项目的优秀实现，特此感谢！

This site is open source. Improve this page.