Content
# XHS AI Toolkit
<p align="center">
<b>Make AI understand your Xiaohongshu (RedNote)</b>
</p>
<p align="center">
<a href="README_CN.md">简体中文</a> | English
</p>
<p align="center">
<img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
<img alt="Platform" src="https://img.shields.io/badge/platform-Linux%20%7C%20macOS-lightgrey.svg">
<img alt="Python" src="https://img.shields.io/badge/python-3.10+-green.svg">
<img alt="MCP" src="https://img.shields.io/badge/MCP-compatible-purple.svg">
</p>
---
AI-powered toolkit for **Xiaohongshu (小红书 / RedNote)** that turns your favorite posts into AI memory.
- **MCP Integration** — Search, browse, comment via AI assistants
- **Trend Tracking** — Auto-generate topic reports with engagement analytics
- **Memory Export** — Convert your liked/saved posts into AI-searchable knowledge base
Built on [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) and [XHS-Downloader](https://github.com/JoeanAmier/XHS-Downloader).
## Features
| Feature | Description |
|---------|-------------|
| Search | Search posts by keywords |
| Feed | Get homepage recommendations |
| Post Details | Fetch post content, comments, engagement stats |
| Comment | Post comments to notes |
| User Profile | Get user info and their posts |
| Trend Tracking | Auto-generate topic analysis reports |
| Long Image Export | Export posts as annotated JPG long images |
| Memory Export | Export liked/saved posts as Markdown for AI memory |
## Quick Start
### 1. Install xiaohongshu-mcp
Download from [GitHub Releases](https://github.com/xpzouying/xiaohongshu-mcp/releases):
```bash
# Linux x64
wget https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-mcp-linux-amd64.tar.gz
wget https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-login-linux-amd64.tar.gz
# macOS ARM
wget https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-mcp-darwin-arm64.tar.gz
wget https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-login-darwin-arm64.tar.gz
```
Install:
```bash
mkdir -p ~/.local/bin
tar -xzf xiaohongshu-mcp-*.tar.gz -C ~/.local/bin/
tar -xzf xiaohongshu-login-*.tar.gz -C ~/.local/bin/
cd ~/.local/bin
mv xiaohongshu-mcp-* xiaohongshu-mcp
mv xiaohongshu-login-* xiaohongshu-login
chmod +x xiaohongshu-mcp xiaohongshu-login
```
### 2. Install This Toolkit
```bash
# Clone to OpenClaw workspace
git clone https://github.com/zhjiang22/openclaw-xhs.git
cp -r openclaw-xhs ~/.openclaw/workspace/skills/xiaohongshu
# Or use symlink
ln -s /path/to/openclaw-xhs ~/.openclaw/workspace/skills/xiaohongshu
# Verify installation
cd ~/.openclaw/workspace/skills/xiaohongshu/scripts
./install-check.sh
```
### 3. Login (Get Cookies)
**Option A: Desktop Environment**
```bash
./login.sh # Opens browser, scan QR code with Xiaohongshu app
```
**Option B: Headless Server**
Get cookies on your local machine, then copy to server:
```bash
# On local machine with GUI
./xiaohongshu-login
# Cookies saved to /tmp/cookies.json
# Copy to server
scp /tmp/cookies.json user@server:~/.xiaohongshu/cookies.json
```
### 4. Start Service
```bash
./start-mcp.sh # Headless mode
./start-mcp.sh --headless=false # Show browser (debug)
```
Service runs at `http://localhost:18060/mcp`.
#### Server Deployment (Headless Linux)
On servers without a desktop environment, the underlying browser requires a virtual display.
`start-mcp.sh` **auto-detects** the environment — if no display is found, it starts Xvfb automatically. Just install it first:
```bash
# Debian/Ubuntu
sudo apt-get install -y xvfb
# CentOS/RHEL
sudo yum install -y xorg-x11-server-Xvfb
```
No extra configuration needed. The script handles:
- Detecting the `DISPLAY` environment variable
- Auto-starting `Xvfb :99` when no display is available
- Cleaning up Xvfb when `stop-mcp.sh` is called
> **Note**: Without Xvfb, login and search will fail on headless servers. See [Issue #3](https://github.com/zhjiang22/openclaw-xhs/issues/3).
## Usage
### Basic Commands
```bash
./status.sh # Check login status
./search.sh "coffee" # Search posts
./recommend.sh # Get recommendations
./post-detail.sh <id> <token> # Get post details
./comment.sh <id> <token> "Great post!" # Comment
./user-profile.sh <user_id> <xsec_token> # Get user profile
```
### Trend Tracking
Auto-search trending posts and generate analysis reports:
```bash
./track-topic.sh "AI" --limit 10
./track-topic.sh "travel" --limit 5 --output report.md
./track-topic.sh "iPhone" --limit 5 --feishu # Export to Feishu
```
### MCP Tools
| Tool | Description |
|------|-------------|
| `check_login_status` | Check login status |
| `search_feeds` | Search posts |
| `list_feeds` | Get homepage feed |
| `get_feed_detail` | Get post details & comments |
| `post_comment_to_feed` | Post comment |
| `user_profile` | Get user profile |
| `like_feed` | Like/unlike post |
| `favorite_feed` | Save/unsave post |
| `publish_content` | Publish image post |
| `publish_with_video` | Publish video post |
### Long Image Export
Export posts as annotated JPG long images (white background, black text):
```bash
# Prepare posts.json
cat > posts.json << 'EOF'
[
{
"title": "Post title",
"author": "Author",
"stats": "13k likes 100 saves",
"desc": "Post summary",
"images": ["https://...webp"],
"per_image_text": {"1": "Caption for 2nd image"}
}
]
EOF
./export-long-image.sh --posts-file posts.json -o output.jpg
```
Requires: Python 3.10+, Pillow (`pip install Pillow`)
## Memory Export (Turn Likes into AI Memory)
Export your liked/saved posts as a searchable knowledge base for AI assistants.
### 1. Install XHS-Downloader
```bash
git clone https://github.com/JoeanAmier/XHS-Downloader.git
cd XHS-Downloader
pip install -r requirements.txt
```
### 2. Extract Post Links (Tampermonkey Script)
1. Install [Tampermonkey](https://www.tampermonkey.net/)
2. Install [XHS-Downloader UserScript](https://raw.githubusercontent.com/JoeanAmier/XHS-Downloader/refs/heads/master/static/XHS-Downloader.js)
3. Go to Xiaohongshu web → Profile → Liked/Saved
4. Click Tampermonkey menu → "Extract liked posts" or "Extract saved posts"
5. Links auto-copied to clipboard
6. Paste into `links.md`
### 3. Download & Export
```bash
# Copy helper scripts
cp tools/xhs-downloader/*.py /path/to/XHS-Downloader/
# Download posts
cd /path/to/XHS-Downloader
python batch_download.py links.md
# Export to workspace
python export_to_workspace.py
# Output: ~/.openclaw/workspace/xhs-memory/
```
### 4. Configure OpenClaw Memory Search
Edit `~/.openclaw/openclaw.json`:
```json
{
"memorySearch": {
"extraPaths": [
"~/.openclaw/workspace/xhs-memory"
]
}
}
```
Now your AI assistant can search your Xiaohongshu favorites!
## Project Structure
```
openclaw-xhs/
├── README.md # English docs
├── README_CN.md # Chinese docs
├── LICENSE
├── SKILL.md # Skill manifest
├── scripts/ # MCP wrapper scripts
│ ├── install-check.sh
│ ├── start-mcp.sh
│ ├── stop-mcp.sh
│ ├── login.sh
│ ├── mcp-call.sh
│ ├── status.sh
│ ├── search.sh
│ ├── recommend.sh
│ ├── post-detail.sh
│ ├── comment.sh
│ ├── user-profile.sh
│ ├── track-topic.sh
│ ├── track-topic.py
│ ├── export-long-image.sh
│ └── export-long-image.py
└── tools/
└── xhs-downloader/ # Memory export tools
├── README.md
├── batch_download.py
├── export_memory.py
└── export_to_workspace.py
```
## Security
This project implements the following security measures:
- **Cookie protection**: Cookie files are copied with `600` permissions (owner-only read/write)
- **Injection prevention**: All shell scripts use `jq` to build JSON payloads instead of string interpolation, preventing shell injection
- **Tool name validation**: MCP tool names are restricted to alphanumeric characters and underscores
- **Path validation**: Cross-skill script calls validate that target paths are within allowed directories
- **Third-party content**: Content fetched from Xiaohongshu is user-generated; exercise appropriate caution
## Disclaimer
This project is a **wrapper layer** for [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp).
- Does NOT contain xiaohongshu-mcp source code
- Users must download xiaohongshu-mcp binaries separately
- Scripts communicate via HTTP protocol only
## Acknowledgments
- [@xpzouying](https://github.com/xpzouying) — [xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)
- [@JoeanAmier](https://github.com/JoeanAmier) — [XHS-Downloader](https://github.com/JoeanAmier/XHS-Downloader) (GPL-3.0)
## License
MIT License (wrapper scripts only)
**Note:** xiaohongshu-mcp has no declared license. Please respect the author's terms.
---
<p align="center">
<b>If this project helps you, please give it a ⭐!</b>
</p>
