XHS Downloader

Clone the XHS-Downloader project from GitHub to get the source code and configuration files.

git clone https://github.com/JoeanAmier/XHS-Downloader.git
cd XHS-Downloader

Install the required Python packages. Using uv is recommended for faster dependency resolution, but pip works equally well.

# Using uv (recommended)
uv sync --no-dev

# Or using pip
pip install -r requirements.txt

Edit the settings file at ./Volume/settings.json to set your cookie, download folder, and file naming preferences. The cookie field is optional but required for private or login-gated content.

{
  "cookie": "your_xiaohongshu_web_cookie_here",
  "work_path": "./Volume",
  "folder_name": "Download",
  "image_format": "AUTO",
  "language": "zh_CN"
}

Launch XHS-Downloader in MCP mode, which starts the HTTP API server on port 5556 and exposes MCP endpoints for AI assistant integration.

python main.py mcp

Point your AI client to the running MCP server. The MCP endpoint is available at the URL below once the server is running.

{
  "mcpServers": {
    "xhs-downloader": {
      "url": "http://127.0.0.1:5556/mcp/"
    }
  }
}

Run the tool in Docker if you prefer a containerized setup. The volume mount persists downloaded files and settings on the host.

docker pull joeanamier/xhs-downloader
docker run -p 5556:5556 -v xhs_downloader_volume:/app/Volume -it joeanamier/xhs-downloader