skill-xhs

A CLI tool and MCP (Model Context Protocol) server for automating XiaoHongShu (Little Red Book) operations.

Features

• Authentication - Login with QR code scan, persistent cookie-based sessions
• Feed Discovery - Browse home page feeds and discover trending content
• Search - Search for notes/posts by keyword
• Publishing - Publish image posts (1-18 images) and video posts
• Engagement - Comment on posts
• MCP Server - Full MCP protocol support for integration with Claude Code and other MCP clients

Installation

Prerequisites

• Node.js >= 18.0.0
• pnpm (recommended) or npm

Setup

# Clone the repository
git clone https://github.com/yourusername/skill-xhs.git
cd skill-xhs

# Install dependencies
pnpm install

# Build the project
npm run build

# Link for global CLI access
npm link

Usage

CLI Commands

Authentication

# Login (opens browser for QR code scan)
skill-xhs login

# Check login status
skill-xhs status

# Logout and clear cookies
skill-xhs logout

# Ensure Chromium is installed
skill-xhs browser

Content Discovery

# Get home page feeds
skill-xhs feeds

# Search for content
skill-xhs search -k "travel"

# Get note details
skill-xhs note-detail --feed-id <id> --xsec-token <token>

Publishing

# Publish an image post (1-18 images)
skill-xhs publish -t image --title "My Post" --content "Description" -m "/path/to/image.jpg"

# Publish multiple images
skill-xhs publish -t image --title "My Gallery" --content "Check these out" \
  -m "/path/to/image1.jpg" -m "/path/to/image2.jpg"

# Publish a video (up to 500MB)
skill-xhs publish -t video --title "My Video" --content "Video description" -m "/path/to/video.mp4"

Engagement

# Comment on a note
skill-xhs comment --feed-id <id> --xsec-token <token> -n "Great content!"

MCP Server

# Start MCP server (stdio mode)
skill-xhs mcp

# Start MCP HTTP server
skill-xhs mcp -m http -p 3000

# List available MCP tools
skill-xhs tools

MCP Tools

When running as an MCP server, the following tools are available:

Tool	Description
xhs_auth_login	Start login process
xhs_auth_logout	Logout and clear cookies
xhs_auth_status	Check login status
xhs_discover_feeds	Get home page feeds
xhs_search_note	Search notes by keyword
xhs_get_note_detail	Get note details
xhs_comment_on_note	Comment on a note
xhs_publish_content	Publish images or videos

Configuration

Configuration is managed through environment variables:

Browser Settings

Variable	Default	Description
XHS_HEADLESS	true	Run browser in headless mode
XHS_BROWSER_TIMEOUT	30000	Default browser timeout (ms)
XHS_LOGIN_TIMEOUT	300	Login timeout (seconds)

Server Settings

Variable	Default	Description
XHS_SERVER_NAME	skill-xhs	MCP server name
XHS_HOST	127.0.0.1	HTTP server host
XHS_PORT	8000	HTTP server port

Logging

Variable	Default	Description
XHS_LOG_LEVEL	INFO	Log level (DEBUG, INFO, WARN, ERROR)
XHS_LOG_FILE	false	Enable file logging
XHS_ENABLE_LOGGING	false	Enable stderr logging in MCP mode

Data Storage

• Cookies: ~/.skill-xhs/cookies.json
• App data: ~/.skill-xhs/

Development

# Run in development mode
npm run dev

# Build for production
npm run build

# Lint code
npm run lint

# Clean build artifacts
npm run clean

Project Structure

src/
├── cli/           # CLI entry point and commands
├── core/          # Core business logic
│   ├── auth/      # Authentication service
│   ├── browser/   # Browser automation
│   ├── feeds/     # Feed discovery and search
│   └── publishing/# Content publishing
├── server/        # MCP server implementation
│   ├── handlers/  # MCP tool handlers
│   └── schemas/   # MCP tool schemas
└── shared/        # Shared utilities and types

Technologies

• TypeScript - Type-safe JavaScript
• Puppeteer - Browser automation
• MCP SDK - Model Context Protocol
• Commander.js - CLI framework
• Webpack - Module bundling

License

MIT License - see LICENSE for details.

Disclaimer

This tool is for educational and automation purposes. Please use responsibly and in accordance with XiaoHongShu's Terms of Service.