# 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>