PlugWiki
XHS-Downloader logo

XHS-Downloader MCP Server: Setup for Claude, Cursor and Other Apps

CommunityRemote
Getjoeanamier/xhs-downloader
Tools
2
1 read · 1 change
Stars
13.2K
on GitHub
Works in
12
apps
Risk
Medium
can write
Auth
token in env

Lets Claude and other assistants read Xiaohongshu (RedNote) post data and download its images or video from a link you paste.

XHS-Downloader is a Python tool for Xiaohongshu (RedNote, 小红书) links, and its MCP mode is one of its server modes alongside a plain API mode. You run it yourself with Python or Docker, and it prints an authentication token on startup that every client must send as a bearer token. The server listens on your machine at port 5556 by default, and downloaded files land in its Volume folder on that machine.

Good for

  • People who want an assistant to pull post text and images from Xiaohongshu links
  • Self-hosters comfortable running a Python or Docker server for a tool they control

Works in

12 should work

Tap an app to see how to set it up and any known problems.

Install XHS-Downloader MCP

Claude Code

  1. 1

    Copy this prompt.

    Add the XHS-Downloader MCP server to Claude Code. Run this command:

claude mcp add --transport http xhs-downloader http://127.0.0.1:5556/mcp --header "Authorization: Bearer <your-token>"

Then check that it loaded and tell me if I need to sign in or restart.
  2. 2

    Paste it into Claude Code. It shows the change and asks before running it.

Requires Your own running XHS-Downloader server (python main.py mcp), A token from python main.py token.

Start the server first (python main.py mcp, uv run main.py mcp, or the Docker image with python main.py mcp) and copy the token it prints. The project documents only the generic mcpServers JSON with a url and an Authorization header; this layout is adapted from it for this client and is not documented by the project.

Built from the package data we hold. Not yet tested by us. Source.

Tools

  • Reads info about a Xiaohongshu (RedNote) post

    Takes a Xiaohongshu or xhslink post link and returns its data (text, images, video info) without downloading any files.

    Try: “Get the details of this Xiaohongshu post: https://www.xiaohongshu.com/explore/...”

    Network · get_detail_data

  • Downloads a Xiaohongshu post's images or video

    Takes a post link and downloads its files to the server's Volume folder. You can ask for specific image numbers only, and optionally also get the post's data back.

    Try: “Download images 1 and 3 from this Xiaohongshu post: https://xhslink.com/...”

    Write · download_detail

Read from the source code

Permissions

medium risk · 4 things to watch

Medium risk

It can download files to the server you run it on, and every client shares one long-lived token. Keep the server's address and token private, and skip download_detail if you only want post data.

What it can do

Watch out for

  • It downloads files to the server's disk

    download_detail saves images or video to the Volume folder on the machine running the server. github.com

  • The server listens on all network interfaces

    MCP mode binds to 0.0.0.0 on port 5556 by default, so other machines on your network can reach it. Every call needs the bearer token, but keep the port closed to untrusted networks. github.com

  • The token is permanent until you delete its key file

    The printed token does not expire on its own. Delete Volume/auth_secret.key to force a new one. github.com

  • It is self-hosted, not a vendor-hosted service

    You run the server yourself, so it only reaches Xiaohongshu for the links you give it. github.com

Security advisories

No published security advisories as of Nov 1, 2026.

Technical details
Turning on read-onlyLeave out download_detail from your client's allowed tools, or only grant get_detail_data, to keep it from writing files.
Talks toXiaohongshu / RedNote (to fetch post data and media)
Sign-in and keysA bearer token printed at server startup, tied to a key file on the server; delete that file to invalidate the token.

Questions

Is this official?

Not for Xiaohongshu; XHS-Downloader is a third-party project, and this MCP mode is part of that project.

Does it need an API key?

It needs a bearer token the server itself generates and prints at startup, not a key from Xiaohongshu.

Is it hosted or local?

You run it yourself, by Python/uv or Docker. There is no shared hosted address.

What is the XHS-Downloader MCP server URL?

Your own server's address with /mcp, for example http://127.0.0.1:5556/mcp when run locally.

Is it free?

Yes, open source under GPL-3.0.

Can it download video, not just images?

Yes. download_detail downloads whatever files the post has, images or video.

Can I make it read-only?

Only by choice: give your client access to get_detail_data alone and leave out download_detail.

Information

updated Nov 2, 2026

Publisher
Community
Transport
Streamable HTTP
Auth
token in env
License
GPL-3.0
Last commit
Oct 31, 2026
Open issues
17

WebsiteGitHubChangelogIssues

Sources

Docs, issue trackers and discussions this page is built from. Issues, quotes and findings above link to their own source.

Show all 2
  1. github.com · github.com
  2. github.com · github.com

Facts from the official MCP registry, GitHub, npm, PyPI and the Docker catalog. Updated Nov 2, 2026.