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 發佈等方面。