XHS-Downloader is an MCP-enabled toolset for automating interaction with the XHS-Downloader project. The MCP mode exposes programmatic access to the server's capabilities, including API-like endpoints and workflow automation via the MCP interface. You can start the MCP server in Python mode and then use the MCP runtime to invoke the available endpoints or scripts that coordinate downloading content, extracting links, and managing metadata. Typical usage involves starting the MCP server, then issuing MCP calls to request details, trigger downloads, or chain actions through the MCP invocation layer. The server supports API-like requests such as /xhs/detail in its HTTP API when run in server mode; through MCP you can orchestrate those actions as part of larger automation pipelines. The documentation bundle also notes optional features like clipboard monitoring, cookie management, and various download modes (CLI, API, and MCP).

Prerequisites:

• Python 3.12+ installed on your system
• Optional: a virtual environment tool (venv) is recommended but not required

1. Clone the repository: git clone https://github.com/JoeanAmier/XHS-Downloader.git cd XHS-Downloader

2. Set up a Python environment and install dependencies: python -m venv venv

   Windows

   .\venv\Scripts\activate.ps1

   macOS/Linux

   source venv/bin/activate pip install -r requirements.txt

3. Run in MCP mode (server mode for MCP): python main.py mcp

4. (Optional) Run in API/standalone server mode to test endpoints before MCP integration: python main.py api

Notes:

• The project provides multiple run modes: source execution, Docker, and MCP. The steps above focus on enabling MCP-based orchestration.
• If you plan to run via Docker or other packaging, follow the Docker run instructions in the README to obtain a containerized MCP setup, then point MCP at the containerized service.

Tips and notes:

• Cookie handling: The project supports browser cookie extraction for higher-quality content; however, some browser cookie retrieval features may become unreliable due to third-party module updates. If cookies are not configured, expect lower-quality downloads.
• Port and volume: The MCP server typically runs on port 5556. If you’re running in a container or behind a reverse proxy, ensure the port is exposed and mapped correctly. For persistent storage, mount a volume to /app/Volume inside containers as described in the Docker section.
• MCP endpoints: In MCP mode you can script interactions with the server's capabilities, including details extraction, link collection, and download orchestration. The API endpoints described in the API mode (e.g., /xhs/detail) are available when running in API mode; MCP can orchestrate similar actions through the MCP interface.
• Environment variables: You may want to set variables such as PORT, volume paths, and any API keys or cookies required by your deployment. Placeholder values are provided in the mcp_config example and should be replaced with real values in your environment.
• Platform considerations: Docker runs may not support clipboard-reading features; if you rely on those, prefer the Program/Source run or API mode rather than Docker in MCP scenarios.