xiaohongshu-mcp

MCP for RedNote (Xiaohongshu) platform.

• My blog article: haha.ai/xiaohongshu-mcp

📌 Please read before submitting a PR: Contributing Guide

If you encounter any issues, be sure to check Common Issues and Solutions first.

After checking the Common Issues list, if you still can't resolve your deployment problems, we strongly recommend using another tool I've created: xpzouying/x-mcp. This tool doesn't require deployment - you only need a browser extension to drive your MCP, making it more user-friendly for non-technical users.

Star History

Appreciation and Support

All donations received for this project will be used for charitable giving. For all charitable donation records, please refer to DONATIONS.md.

When donating, please note "MCP" and your name. If you need to correct/withdraw your name attribution, please open an Issue or contact via email.

Alipay (QR code not displayed):

Donate via Alipay to xpzouying@gmail.com.

WeChat:

Project Overview

Main Features

💡 Tip: Click on the feature titles below to expand and view video demonstrations

1. Login and Check Login Status

The first step is required - RedNote needs to be logged in. You can check current login status.

Login Demo:

https://github.com/user-attachments/assets/8b05eb42-d437-41b7-9235-e2143f19e8b7

Check Login Status Demo:

https://github.com/user-attachments/assets/bd9a9a4a-58cb-4421-b8f3-015f703ce1f9

2. Publish Image and Text Content

Supports publishing image and text content to RedNote, including title, content description, and images.

Image Support Methods:

Supports two image input methods:

1. HTTP/HTTPS Image Links

["https://example.com/image1.jpg", "https://example.com/image2.png"]

1. Local Image Absolute Paths (Recommended) ["/Users/username/Pictures/image1.jpg", "/home/user/images/image2.png"]

Why Local Paths are Recommended:

• ✅ Better stability, not dependent on network
• ✅ Faster upload speed
• ✅ Avoid image link expiration issues
• ✅ Support more image formats

Publish Image-Text Post Demo:

https://github.com/user-attachments/assets/8aee0814-eb96-40af-b871-e66e6bbb6b06

3. Publish Video Content

Supports publishing video content to RedNote, including title, content description, and local video files.

Video Support Methods:

Only supports local video file absolute paths:

"/Users/username/Videos/video.mp4"

Features:

• ✅ Supports local video file upload
• ✅ Automatic video format processing
• ✅ Supports title, content description, and tags
• ✅ Automatically publishes after video processing is complete

Important Notes:

• Only supports local video files, not HTTP links
• Video processing takes longer, please be patient
• Recommended video file size should not exceed 1GB

4. Search Content

Search RedNote content by keywords.

Search Posts Demo:

https://github.com/user-attachments/assets/03c5077d-6160-4b18-b629-2e40933a1fd3

5. Get Recommendation List

Get RedNote homepage recommendation content list.

Get Recommendation List Demo:

https://github.com/user-attachments/assets/110fc15d-46f2-4cca-bdad-9de5b5b8cc28

6. Get Post Details (Including Interaction Data and Comments)

Get complete details of RedNote posts, including:

• Post content (title, description, images, etc.)
• User information
• Interaction data (likes, favorites, shares, comment count)
• Comment list and sub-comments

⚠️ Important Note:

• Both post ID and xsec_token are required (both parameters are essential)
• These two parameters can be obtained from Feed list or search results
• Must login first to use this feature

Get Post Details Demo:

https://github.com/user-attachments/assets/76a26130-a216-4371-a6b3-937b8fda092a

7. Post Comments to Posts

Supports automatically posting comments to RedNote posts.

Feature Description:

• Automatically locate comment input box
• Input comment content and publish
• Supports HTTP API and MCP tool calls

⚠️ Important Note:

• Must login first to use this feature
• Need to provide post ID, xsec_token, and comment content
• These parameters can be obtained from Feed list or search results

Post Comment Demo:

https://github.com/user-attachments/assets/cc385b6c-422c-489b-a5fc-63e92c695b80

8. Get User Profile

Get RedNote user's personal profile information, including basic user information and note content.

Feature Description:

• Get user basic information (nickname, bio, avatar, etc.)
• Get follower count, following count, likes count statistics
• Get user's published note content list
• Supports HTTP API and MCP tool calls

⚠️ Important Note:

• Must login first to use this feature
• Need to provide user ID and xsec_token
• These parameters can be obtained from Feed list or search results

Returned Information Includes:

• User basic info: nickname, bio, avatar, verification status
• Statistics: following count, follower count, likes count, note count
• Note list: all public notes published by the user

9. Reply to Comments

Reply to a specific comment under a note, supporting precise replies to specific users' comments.

Feature Description:

• Reply to a specific comment under a note
• Support locating target comment by comment ID or user ID
• Requires feed_id, xsec_token, comment_id/user_id, and reply content

⚠️ Important Note:

• Must login first to use this feature
• At least one of comment_id or user_id must be provided
• These parameters can be obtained from the comment list in post details

10. Like / Unlike

Like or unlike a note, with smart detection of current status to avoid duplicate operations.

Feature Description:

• Like or unlike a specified note
• Smart detection: skips liking if already liked, skips unliking if not liked
• Requires feed_id and xsec_token

⚠️ Important Note:

• Must login first to use this feature
• Default action is like, set unlike=true to unlike

11. Favorite / Unfavorite

Favorite a note or unfavorite it, with smart detection of current status to avoid duplicate operations.

Feature Description:

• Favorite or unfavorite a specified note
• Smart detection: skips favoriting if already favorited, skips unfavoriting if not favorited
• Requires feed_id and xsec_token

⚠️ Important Note:

• Must login first to use this feature
• Default action is favorite, set unfavorite=true to unfavorite

RedNote Basic Operation Knowledge

• Title: (Very Important) RedNote requires titles to not exceed 20 characters
• Content: (Very Important) Content cannot exceed 1000 characters
• Currently supports both image-text and video posting: From a recommendation perspective, image-text posts get better traffic than video or pure text.
• (Low priority) Pure text support can be considered. 1. I personally feel pure text would greatly increase operation complexity; 2. Pure text has low value in my use scenarios.
• Tags: Now supported. Adding appropriate tags can bring more traffic.
• According to my practical experience, RedNote should allow 50 posts per day.
• (Very Important) RedNote does not allow the same account to login on multiple web platforms. If you login to the current xiaohongshu-mcp, don't login to that account on other web platforms, otherwise it will "kick out" the current MCP account login. You can use the mobile app to check current account information.

Risk Explanation

1. This project is open-sourced based on another project of mine. The original project has been running stably for over a year without any account bans, only occasional cookie expiration requiring re-login.
2. I used Claude Code CLI integration and verified stable automated operation for several weeks before open-sourcing.

This project is for learning purposes only. All illegal activities are prohibited.

Practical Results

First day likes/favorites reached 999+,

Results after about a week

1. Usage Tutorial

1.1. Quick Start (Recommended)

Method 1: Download Pre-compiled Binaries

Download pre-compiled binaries for your platform directly from GitHub Releases:

Main Program (MCP Service):

• macOS Apple Silicon: xiaohongshu-mcp-darwin-arm64
• macOS Intel: xiaohongshu-mcp-darwin-amd64
• Windows x64: xiaohongshu-mcp-windows-amd64.exe
• Linux x64: xiaohongshu-mcp-linux-amd64

Login Tool:

• macOS Apple Silicon: xiaohongshu-login-darwin-arm64
• macOS Intel: xiaohongshu-login-darwin-amd64
• Windows x64: xiaohongshu-login-windows-amd64.exe
• Linux x64: xiaohongshu-login-linux-amd64

Usage Steps:

# 1. First run the login tool
chmod +x xiaohongshu-login-darwin-arm64
./xiaohongshu-login-darwin-arm64

# 2. Then start the MCP service
chmod +x xiaohongshu-mcp-darwin-arm64
./xiaohongshu-mcp-darwin-arm64

⚠️ Important Note: The headless browser will be automatically downloaded on first run (about 150MB), please ensure a stable network connection. Subsequent runs will not require re-downloading.

Method 2: Build from Source

Build from Source Details

Requires Golang environment. For installation instructions, please refer to Golang Official Documentation.

Set Go domestic proxy source:

# Configure GOPROXY environment variable, choose one of the following three

# 1. Qiniu CDN
go env -w  GOPROXY=https://goproxy.cn,direct

# 2. Alibaba Cloud
go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/,direct

# 3. Official
go env -w  GOPROXY=https://goproxy.io,direct

Method 3: Using Docker Container (Simplest)

Docker Deployment Details

Using Docker deployment is the simplest method, requiring no development environment installation.

1. Pull Image from Docker Hub (Recommended)

We provide pre-built Docker images that can be directly pulled from Docker Hub:

# Pull the latest image
docker pull xpzouying/xiaohongshu-mcp

Docker Hub URL: https://hub.docker.com/r/xpzouying/xiaohongshu-mcp

2. Start with Docker Compose (Recommended)

We provide a pre-configured docker-compose.yml file that can be used directly:

# Download docker-compose.yml
wget https://raw.githubusercontent.com/xpzouying/xiaohongshu-mcp/main/docker/docker-compose.yml

# Or if you've already cloned the project, enter the docker directory
cd docker

# Start service
docker compose up -d

# View logs
docker compose logs -f

# Stop service
docker compose stop

3. Build Image Yourself (Optional)

If you need to customize or modify the code, you can build the image yourself:

# Run in project root directory
docker build -t xpzouying/xiaohongshu-mcp .

4. Configuration Notes

The Docker version automatically:

• Configures CloakBrowser Chromium and Chinese fonts
• Mounts ./data for storing cookies and runtime data directories
• Mounts ./images for storing publish images
• Exposes port 18060 for MCP connection

For detailed instructions, please refer to: Docker Deployment Guide

For Windows issues, check here first: Windows Installation Guide

1.2. Login

First time requires manual login to save RedNote login status.

Using Binary Files:

# Run the login tool for your platform
./xiaohongshu-login-darwin-arm64

Using Source Code:

go run cmd/login/main.go

1.3. Start MCP Service

Start xiaohongshu-mcp service.

Using Binary Files:

# Default: Headless mode, no browser interface
./xiaohongshu-mcp-darwin-arm64

# Non-headless mode, with browser interface
./xiaohongshu-mcp-darwin-arm64 -headless=false

Using Source Code:

```bash

Default: Headless mode, no bro