1# XHS AI Toolkit
2 
3<p align="center">
4  <b>Make AI understand your Xiaohongshu (RedNote)</b>
5</p>
6 
7<p align="center">
8  <a href="README_CN.md">简体中文</a> | English
9</p>
10 
11<p align="center">
12  <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
13  <img alt="Platform" src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS-lightgrey.svg">
14  <img alt="Python" src="https://img.shields.io/badge/python-3.10+-green.svg">
15  <img alt="MCP" src="https://img.shields.io/badge/MCP-compatible-purple.svg">
16</p>
17 
18---
19 
20AI-powered toolkit for **Xiaohongshu (小红书 / RedNote)** that turns your favorite posts into AI memory.
21 
22- **MCP Integration** — Search, browse, comment via AI assistants
23- **Trend Tracking** — Auto-generate topic reports with engagement analytics
24- **Memory Export** — Convert your liked/saved posts into AI-searchable knowledge base
25 
26Built on [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) and [XHS-Downloader](https://github.com/JoeanAmier/XHS-Downloader).
27 
28## Features
29 
30| Feature | Description |
31|---------|-------------|
32| Search | Search posts by keywords |
33| Feed | Get homepage recommendations |
34| Post Details | Fetch post content, comments, engagement stats |
35| Comment | Post comments to notes |
36| User Profile | Get user info and their posts |
37| Trend Tracking | Auto-generate topic analysis reports |
38| Long Image Export | Export posts as annotated JPG long images |
39| Memory Export | Export liked/saved posts as Markdown for AI memory |
40 
41## Quick Start
42 
43### 1. Install xiaohongshu-mcp
44 
45Download from [GitHub Releases](https://github.com/xpzouying/xiaohongshu-mcp/releases):
46 
47```bash
48# Linux x64
49wget https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-mcp-linux-amd64.tar.gz
50wget https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-login-linux-amd64.tar.gz
51 
52# macOS ARM
53wget https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-mcp-darwin-arm64.tar.gz
54wget https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-login-darwin-arm64.tar.gz
55```
56 
57Install:
58 
59```bash
60mkdir -p ~/.local/bin
61tar -xzf xiaohongshu-mcp-*.tar.gz -C ~/.local/bin/
62tar -xzf xiaohongshu-login-*.tar.gz -C ~/.local/bin/
63 
64cd ~/.local/bin
65mv xiaohongshu-mcp-* xiaohongshu-mcp
66mv xiaohongshu-login-* xiaohongshu-login
67chmod +x xiaohongshu-mcp xiaohongshu-login
68```
69 
70### 2. Install This Toolkit
71 
72```bash
73# Clone to OpenClaw workspace
74git clone https://github.com/zhjiang22/openclaw-xhs.git
75cp -r openclaw-xhs ~/.openclaw/workspace/skills/xiaohongshu
76 
77# Or use symlink
78ln -s /path/to/openclaw-xhs ~/.openclaw/workspace/skills/xiaohongshu
79 
80# Verify installation
81cd ~/.openclaw/workspace/skills/xiaohongshu/scripts
82./install-check.sh
83```
84 
85### 3. Login (Get Cookies)
86 
87**Option A: Desktop Environment**
88 
89```bash
90./login.sh  # Opens browser, scan QR code with Xiaohongshu app
91```
92 
93**Option B: Headless Server**
94 
95Get cookies on your local machine, then copy to server:
96 
97```bash
98# On local machine with GUI
99./xiaohongshu-login
100# Cookies saved to /tmp/cookies.json
101 
102# Copy to server
103scp /tmp/cookies.json user@server:~/.xiaohongshu/cookies.json
104```
105 
106### 4. Start Service
107 
108```bash
109./start-mcp.sh              # Headless mode
110./start-mcp.sh --headless=false  # Show browser (debug)
111```
112 
113Service runs at `http://localhost:18060/mcp`.
114 
115#### Server Deployment (Headless Linux)
116 
117On servers without a desktop environment, the underlying browser requires a virtual display.
118`start-mcp.sh` **auto-detects** the environment — if no display is found, it starts Xvfb automatically. Just install it first:
119 
120```bash
121# Debian/Ubuntu
122sudo apt-get install -y xvfb
123 
124# CentOS/RHEL
125sudo yum install -y xorg-x11-server-Xvfb
126```
127 
128No extra configuration needed. The script handles:
129- Detecting the `DISPLAY` environment variable
130- Auto-starting `Xvfb :99` when no display is available
131- Cleaning up Xvfb when `stop-mcp.sh` is called
132 
133> **Note**: Without Xvfb, login and search will fail on headless servers. See [Issue #3](https://github.com/zhjiang22/openclaw-xhs/issues/3).
134 
135## Usage
136 
137### Basic Commands
138 
139```bash
140./status.sh                    # Check login status
141./search.sh "coffee"           # Search posts
142./recommend.sh                 # Get recommendations
143./post-detail.sh <id> <token>  # Get post details
144./comment.sh <id> <token> "Great post!"  # Comment
145./user-profile.sh <user_id> <xsec_token>  # Get user profile
146```
147 
148### Trend Tracking
149 
150Auto-search trending posts and generate analysis reports:
151 
152```bash
153./track-topic.sh "AI" --limit 10
154./track-topic.sh "travel" --limit 5 --output report.md
155./track-topic.sh "iPhone" --limit 5 --feishu  # Export to Feishu
156```
157 
158### MCP Tools
159 
160| Tool | Description |
161|------|-------------|
162| `check_login_status` | Check login status |
163| `search_feeds` | Search posts |
164| `list_feeds` | Get homepage feed |
165| `get_feed_detail` | Get post details & comments |
166| `post_comment_to_feed` | Post comment |
167| `user_profile` | Get user profile |
168| `like_feed` | Like/unlike post |
169| `favorite_feed` | Save/unsave post |
170| `publish_content` | Publish image post |
171| `publish_with_video` | Publish video post |
172 
173### Long Image Export
174 
175Export posts as annotated JPG long images (white background, black text):
176 
177```bash
178# Prepare posts.json
179cat > posts.json << 'EOF'
180[
181  {
182    "title": "Post title",
183    "author": "Author",
184    "stats": "13k likes 100 saves",
185    "desc": "Post summary",
186    "images": ["https://...webp"],
187    "per_image_text": {"1": "Caption for 2nd image"}
188  }
189]
190EOF
191 
192./export-long-image.sh --posts-file posts.json -o output.jpg
193```
194 
195Requires: Python 3.10+, Pillow (`pip install Pillow`)
196 
197## Memory Export (Turn Likes into AI Memory)
198 
199Export your liked/saved posts as a searchable knowledge base for AI assistants.
200 
201### 1. Install XHS-Downloader
202 
203```bash
204git clone https://github.com/JoeanAmier/XHS-Downloader.git
205cd XHS-Downloader
206pip install -r requirements.txt
207```
208 
209### 2. Extract Post Links (Tampermonkey Script)
210 
2111. Install [Tampermonkey](https://www.tampermonkey.net/)
2122. Install [XHS-Downloader UserScript](https://raw.githubusercontent.com/JoeanAmier/XHS-Downloader/refs/heads/master/static/XHS-Downloader.js)
2133. Go to Xiaohongshu web → Profile → Liked/Saved
2144. Click Tampermonkey menu → "Extract liked posts" or "Extract saved posts"
2155. Links auto-copied to clipboard
2166. Paste into `links.md`
217 
218### 3. Download & Export
219 
220```bash
221# Copy helper scripts
222cp tools/xhs-downloader/*.py /path/to/XHS-Downloader/
223 
224# Download posts
225cd /path/to/XHS-Downloader
226python batch_download.py links.md
227 
228# Export to workspace
229python export_to_workspace.py
230# Output: ~/.openclaw/workspace/xhs-memory/
231```
232 
233### 4. Configure OpenClaw Memory Search
234 
235Edit `~/.openclaw/openclaw.json`:
236 
237```json
238{
239  "memorySearch": {
240    "extraPaths": [
241      "~/.openclaw/workspace/xhs-memory"
242    ]
243  }
244}
245```
246 
247Now your AI assistant can search your Xiaohongshu favorites!
248 
249## Project Structure
250 
251```
252openclaw-xhs/
253├── README.md             # English docs
254├── README_CN.md          # Chinese docs
255├── LICENSE
256├── SKILL.md              # Skill manifest
257├── scripts/              # MCP wrapper scripts
258│   ├── install-check.sh
259│   ├── start-mcp.sh
260│   ├── stop-mcp.sh
261│   ├── login.sh
262│   ├── mcp-call.sh
263│   ├── status.sh
264│   ├── search.sh
265│   ├── recommend.sh
266│   ├── post-detail.sh
267│   ├── comment.sh
268│   ├── user-profile.sh
269│   ├── track-topic.sh
270│   ├── track-topic.py
271│   ├── export-long-image.sh
272│   └── export-long-image.py
273└── tools/
274    └── xhs-downloader/   # Memory export tools
275        ├── README.md
276        ├── batch_download.py
277        ├── export_memory.py
278        └── export_to_workspace.py
279```
280 
281## Security
282 
283This project implements the following security measures:
284 
285- **Cookie protection**: Cookie files are copied with `600` permissions (owner-only read/write)
286- **Injection prevention**: All shell scripts use `jq` to build JSON payloads instead of string interpolation, preventing shell injection
287- **Tool name validation**: MCP tool names are restricted to alphanumeric characters and underscores
288- **Path validation**: Cross-skill script calls validate that target paths are within allowed directories
289- **Third-party content**: Content fetched from Xiaohongshu is user-generated; exercise appropriate caution
290 
291 
292## Disclaimer
293 
294This project is a **wrapper layer** for [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp).
295 
296- Does NOT contain xiaohongshu-mcp source code
297- Users must download xiaohongshu-mcp binaries separately
298- Scripts communicate via HTTP protocol only
299 
300## Acknowledgments
301 
302- [@xpzouying](https://github.com/xpzouying) — [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)
303- [@JoeanAmier](https://github.com/JoeanAmier) — [XHS-Downloader](https://github.com/JoeanAmier/XHS-Downloader) (GPL-3.0)
304 
305## License
306 
307MIT License (wrapper scripts only)
308 
309**Note:** xiaohongshu-mcp has no declared license. Please respect the author's terms.
310 
311---
312 
313<p align="center">
314  <b>If this project helps you, please give it a ⭐!</b>
315</p>
316