Xhs MCP

🚀 xhs-mcp

简体中文 | English

xhs-mcp provides a unified command-line entry xhs-mcp and includes built-in subcommands for the MCP server. It is a Model Context Protocol (MCP) server and CLI tool for Xiaohongshu (xiaohongshu.com), supporting automation capabilities such as login, publishing, searching, and recommendation (based on Puppeteer).

📦 NPM Information

• Package Name: xhs-mcp
• Run CLI (Recommended): npx xhs-mcp <subcommand>
• Start MCP: npx xhs-mcp mcp [--mode stdio|http] [--port 3000]

✨ Features

• Authentication: Login, logout, and status check
• Publishing: Publish images and videos
  • Image Publishing: Title ≤ 20 characters (40 display units), content ≤ 1000, up to 18 images
  • Video Publishing: Supports MP4, MOV, AVI, MKV, WebM, FLV, WMV formats
  • ⭐ New Feature: Supports automatic download of image URLs (HTTP/HTTPS)
  • ⭐ New Feature: Precise verification of title width (2 units for CJK characters, 1 unit for ASCII characters)
  • Supports local image paths
  • Supports mixed use of URLs and local paths
  • Intelligent caching mechanism to avoid repeated downloads
• Discovery: Recommendation, search, details, and comments
• Automation: Puppeteer-driven, headless mode, and cookie management

📋 Available Tools

• 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 (Unified publishing interface: type, title, content, media_paths, tags)
  • Image Publishing: 1 - 18 image files or URLs
  • Video Publishing: Exactly 1 video file
  • Mixed Use: Supports mixed use of image URLs and local paths

🚀 Quick Start (MCP)

Stdio Mode (Default)

npx xhs-mcp mcp

# Debug logging
XHS_ENABLE_LOGGING=true npx xhs-mcp mcp

First-run prompt: If the Puppeteer browser is not installed, first execute

npx xhs-mcp browser    # Automatically check and install Chromium, display the executable path
# or
npx puppeteer browsers install chrome

Example output:

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

Verify the MCP connection:

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

HTTP Mode

# Start the HTTP server (default port 3000)
npx xhs-mcp mcp --mode http

# Specify the port
npx xhs-mcp mcp --mode http --port 8080

# Debug mode
XHS_ENABLE_LOGGING=true npx xhs-mcp mcp --mode http

The HTTP server supports:

• Streamable HTTP (Protocol version 2025-03-26) - Endpoint: /mcp
• SSE (Protocol version 2024-11-05) - Endpoints: /sse and /messages
• Health check - Endpoint: /health

For detailed documentation, please refer to: HTTP Transports

🧰 CLI Subcommands

# Authentication
npx xhs-mcp login --timeout 120
npx xhs-mcp logout
npx xhs-mcp status

# Browser dependencies
npx xhs-mcp browser [--with-deps]  # Check and install Chromium, display the executable path

# Discovery and retrieval
npx xhs-mcp feeds [-b /path/to/chromium]
npx xhs-mcp search -k keyword [-b /path/to/chromium]
npx xhs-mcp note-detail --feed-id <id> --xsec-token <token> [-b /path/to/chromium]

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

# Publishing
# Use local images
npx xhs-mcp publish --type image --title title --content content -m path1.jpg,path2.png --tags a,b [-b /path/to/chromium]

# ⭐ Use image URLs (automatically downloaded)
npx xhs-mcp publish --type image --title title --content content -m "https://example.com/img1.jpg,https://example.com/img2.png" --tags a,b

# Mixed use of URLs and local paths
npx xhs-mcp publish --type image --title title --content content -m "https://example.com/img1.jpg,./local/img2.jpg" --tags a,b

# Publish videos
npx xhs-mcp publish --type video --title video_title --content video_description -m path/to/video.mp4 --tags a,b [-b /path/to/chromium]

# View available tools
npx xhs-mcp tools [--detailed] [--json]

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

🔧 Client Access (Cursor)

Stdio Mode

.cursor/mcp.json:

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

HTTP Mode

.cursor/mcp.json:

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

Or directly connect using an HTTP client:

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

⚠️ Important Notes

• Image Publishing: Title ≤ 20, content ≤ 1000, images ≤ 18
• Video Publishing: Supports multiple formats, recommended file size ≤ 500MB
• Avoid logging in to the web on multiple devices with the same account simultaneously
• Reasonably control the posting frequency
• Image URLs are automatically downloaded to the ./temp_images/ directory (automatically cached)
• Supported image URL formats: JPEG, PNG, GIF, WebP, BMP

📖 Documentation and Examples

📚 Documentation

• Complete Usage Guide - Detailed usage instructions and best practices
• HTTP Transport Documentation - HTTP/SSE mode configuration
• Publishing Guide - NPM publishing process

🎨 Examples

• Usage Examples - Image and publishing examples
• Example Images - Example images for testing

🧪 Testing

• Run Tests - Testing instructions and usage
• Run all tests: npm test

🛠️ Build Instructions

• Use a single production build configuration: config/webpack.config.js
• Development and optimization variants have been removed; for development, directly run:
  • npm run dev (Directly run the TypeScript CLI)
  • npm run build (Package to dist/xhs-mcp.js)

🙏 Acknowledgments

This project is refactored and extended based on xiaohongshu-mcp (TypeScript, Puppeteer, MCP optimization, log cleanup, NPM publishing).