# xhs-mcp

简体中文 | [English](./README.en.md)

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

> 免责声明：本项目是社区维护的非官方工具，不隶属于、未获得小红书或其关联公司的背书。使用者需要自行遵守小红书平台规则、账号安全要求和适用法律法规。发布、评论、删除等操作会真实作用于你的账号，请谨慎使用。

[![npm version](https://img.shields.io/npm/v/xhs-mcp.svg)](https://www.npmjs.com/package/xhs-mcp)
[![npm downloads](https://img.shields.io/npm/dm/xhs-mcp.svg)](https://www.npmjs.com/package/xhs-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 📦 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 管理
- 图片处理：支持图片 URL 下载、缓存、压缩和本地路径混合

## 📋 可用工具

- `xhs_auth_login`、`xhs_auth_logout`、`xhs_auth_status`
- `xhs_discover_feeds`、`xhs_search_note`、`xhs_get_note_detail`
- `xhs_comment_on_note`
- `xhs_get_user_notes`、`xhs_delete_note`（用户笔记管理）
- `xhs_get_favorites_list`、`xhs_get_batch_notes_from_favorites`（收藏夹读取）
- `xhs_download_note_images`（笔记图片下载）
- `xhs_publish_content`（统一发布接口：`type`、`title`、`content`、`media_paths`、`tags`）
  - **图片发布**：1-18个图片文件或URL
  - **视频发布**：恰好1个视频文件
  - **混合使用**：支持图片URL和本地路径混合

## 🚀 快速开始（MCP）

### Stdio 模式（默认）

```bash
npx xhs-mcp mcp

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

> 首次运行提示：如果未安装 Puppeteer 浏览器，先执行
>
> ```bash
> npx xhs-mcp browser    # 自动检查并安装 Chromium，显示可执行路径
> # 或
> npx puppeteer browsers install chrome
> ```
>
> 输出示例：
> ```json
> {
>   "success": true,
>   "message": "Chromium is ready",
>   "data": {
>     "installed": true,
>     "executablePath": "/path/to/chromium"
>   }
> }
> ```

验证 MCP 连接：

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

### HTTP 模式

```bash
# 启动 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](./docs/HTTP_TRANSPORTS.md)

## 🧰 CLI 子命令

```bash
# 认证
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 usernote list [-l 20] [--cursor <cursor>] [-b /path/to/chromium]

# 删除用户笔记
npx xhs-mcp usernote delete --note-id <id> [-b /path/to/chromium]
npx xhs-mcp usernote delete --last-published [-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`：

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

### HTTP 模式

`.cursor/mcp.json`：

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

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

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

## ⚠️ 注意事项

- 本工具依赖浏览器自动化和小红书 Web 页面结构，页面改版时搜索、收藏夹、发布等能力可能需要适配。
- 登录 Cookie 默认保存到 `~/.xhs-mcp/cookies.json`。Cookie 等同于登录凭证，不要提交到 Git、issue、日志或截图中。
- 高风险工具包括：`xhs_publish_content`、`xhs_comment_on_note`、`xhs_delete_note`。建议先使用测试账号验证流程。
- **图文发布**：标题≤20、内容≤1000、图片≤18
- **视频发布**：支持多种格式，文件大小建议≤500MB
- 避免同账号多端同时网页登录
- 合理控制发帖频率
- 图片 URL 自动下载到 `./temp_images/` 目录（自动缓存）
- 图片 URL 支持格式：JPEG、PNG、GIF、WebP、BMP

## 📖 文档和示例

### 📚 文档
- [完整使用指南](./docs/USAGE_GUIDE.md) - 详细的使用说明和最佳实践
- [HTTP 传输文档](./docs/HTTP_TRANSPORTS.md) - HTTP/SSE 模式配置
- [发布指南](./docs/PUBLISH_GUIDE.md) - NPM 发布流程
- [开源发布检查清单](./docs/OPEN_SOURCE_CHECKLIST.md) - GitHub 发布前检查
- [安全策略](./SECURITY.md) - Cookie 与账号安全说明

### 🎨 示例
- [使用示例](./examples/README.md) - 图片和发布示例
- [示例图片](./examples/images/) - 可用于测试的示例图片

### 🧪 测试
- [运行测试](./tests/README.md) - 测试说明和用法
- 运行所有测试：`npm test`

## 🛠️ 构建说明

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

## 🙏 致谢

基于 [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) 重构与扩展（TypeScript、Puppeteer、MCP 优化、日志清理、NPM 发布）。