XHS-Downloader

Overview

XHS-Downloader (by JoeanAmier) is a popular open-source Python tool dedicated to Xiaohongshu (小红书, also known as REDnote or XHS). It excels at link extraction, note information collection, and downloading high-quality media files (images, videos, Live Photos) without watermarks.

The project supports batch operations for user posts, collections, likes, albums, and search results. Importantly, it includes native MCP (Model Context Protocol) server mode, allowing AI coding agents and assistants (such as Claude Desktop, Cursor, etc.) to directly control downloading, extraction, and content collection tasks.

Key Features

• Link Extraction: Extract published posts, favorites, likes, album links, search results, and user links.
• Note Information Collection: Gather detailed metadata for Xiaohongshu notes.
• No-Watermark Downloads: Download images, videos, and Live Photos in high quality.
• Batch & Deduplication: Automatic skipping of previously downloaded notes using a local database.
• MCP Server Mode: Run as an MCP server (python main.py mcp) for AI agent integration.
• Breakpoint Resume & Custom Naming: Support for resumable downloads and customizable file name formats.
• API & User Script Support: Works with browser userscripts for one-click task pushing.
• CLI + GUI Modes: Easy program execution or source code run.

How It Works (MCP Mode)

1. Run the MCP server:

   python main.py mcp
   

2. The server listens at http://127.0.0.1:5556/mcp/ (or configured port).
3. Add the MCP server to your AI client configuration.
4. AI agents can call tools to extract links, collect note data, or trigger downloads directly.

This makes XHS-Downloader a powerful backend for agentic workflows involving Xiaohongshu content.

Use Cases

• AI-Powered Content Archiving: Let AI agents automatically collect and download specific user notes or topics.
• Batch Media Download: Research, curation, or backup of Xiaohongshu posts at scale.
• No-Watermark Media Saving: Obtain clean assets for personal, educational, or creative use.
• Data Collection Pipelines: Integrate with other MCP tools for research or analysis of XHS trends.
• Automation Scripts: Combine with browser userscripts for seamless workflow.

Getting Started

Quick Run (Recommended)

• Download the latest release from GitHub Releases.
• Unzip and run the executable (main on Windows/macOS).

Source Code + MCP Mode

git clone https://github.com/JoeanAmier/XHS-Downloader.git
cd XHS-Downloader
pip install -r requirements.txt
python main.py mcp   # Start MCP server

For full features including user scripts and API usage, refer to the README.

Benefits

XHS-Downloader stands out for its reliability, deduplication, resumable downloads, and direct MCP support — making it one of the most advanced open-source tools for Xiaohongshu content handling. It serves both manual users and AI agent ecosystems effectively while remaining lightweight and actively maintained.

Note: Use responsibly and respect Xiaohongshu's terms of service and copyright.