JoeanAmier/XHS-Downloader

What it solves

Xiaohongshu (also known as RedNote) is a social platform where users share photos, videos, and text posts. There is no official way to download those posts directly. This tool solves that by letting users paste a post link and automatically extracting all downloadable content — images, videos, covers, and live photos — saving them locally. It also handles multiple links at once and can skip already downloaded files.

How it works

The program parses Xiaohongshu post URLs (including short links like xhslink.com), then uses the platform's web data to fetch the post's information and download links. It offers several ways to use it:

• A graphical user interface (GUI) and a terminal user interface (TUI) for interactive use.
• A command-line mode for scripted or bulk downloads.
• An API mode that runs a local server (on port 5556) and lets other programs request post data or trigger downloads via HTTP.
• An MCP (Model Context Protocol) mode so AI assistants and similar tools can call the downloader.
• A browser userscript (for Tampermonkey) that can extract post links from the Discover, user profile, search, and other pages, and can push download tasks to the running program.

Configuration is stored in a settings.json file, and the program can read a Cookie (optional, but improves video quality) and use a proxy if needed. It also has a delay mechanism to avoid overloading the platform.

Who it’s for

It's aimed at anyone who wants to download content from Xiaohongshu for personal archiving, research, or other legitimate purposes. It is also useful for developers who want to integrate Xiaohongshu content retrieval into their own applications, since it provides an API and MCP interface, and the source code can be used as a library.

Highlights

• Multiple ways to run: GUI, TUI, CLI, Docker, API server, and MCP server.
• Can download images, videos (including with higher quality when a Cookie is provided), video covers, and live photos.
• Batch processing: multiple links can be provided at once.
• Automatically skips already downloaded files and keeps a record of downloaded post IDs.
• Customizable file naming and folder structure; can save each author's posts in separate folders.
• Supports downloading only specific images from a multi-image post via an index list.
• The browser userscript can extract post links from many parts of the site and push them to the main program.
• Includes authentication for API and MCP access to prevent unauthorized use.