# xhs-mcp

> Lightweight MCP server for **Xiaohongshu** (Little Red Book / RED) — China's #1 lifestyle platform with 300M+ monthly active users.

**No Docker. No Chromium. Just `npx`.**

```bash
npx xhs-mcp-server
```

## Why this exists

Xiaohongshu (小红书) is where Chinese consumers discover products, share reviews, and follow trends. If you're building for the Chinese market — or just want to understand what's trending there — you need data from this platform.

Existing solutions require Docker + Chromium (heavy, fragile). This server uses direct HTTP APIs, so it starts in <1 second and works anywhere Node.js runs.

## What you can do

| Tool | Description |
|------|-------------|
| `xhs_search` | Search notes by keyword with sorting and filtering |
| `xhs_note_detail` | Get full content, images, and metrics for any note |
| `xhs_user_profile` | Get creator profiles with follower/engagement stats |
| `xhs_user_notes` | List all notes from a specific creator |
| `xhs_explore` | Get the current trending/recommended feed |

## Quick start

### 1. Get your cookie

Log in to [xiaohongshu.com](https://www.xiaohongshu.com) in Chrome, then:

1. Open DevTools (`F12`)
2. Go to **Application** tab → **Cookies** → `https://www.xiaohongshu.com`
3. Copy the entire cookie string (or use a browser extension like "EditThisCookie" to export)

### 2. Add to your AI tool

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "xhs": {
      "command": "npx",
      "args": ["-y", "xhs-mcp-server"],
      "env": {
        "XHS_COOKIE": "your_cookie_string_here"
      }
    }
  }
}
```

**Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "xhs": {
      "command": "npx",
      "args": ["-y", "xhs-mcp-server"],
      "env": {
        "XHS_COOKIE": "your_cookie_string_here"
      }
    }
  }
}
```

**Claude Code**:

```bash
claude mcp add xhs -- npx -y xhs-mcp-server
# Then set XHS_COOKIE in your environment
```

### 3. Use it

Ask your AI assistant:

- "Search Xiaohongshu for skincare trends"
- "Find the top creators posting about coffee in Shanghai"
- "What's trending on Xiaohongshu right now?"
- "Analyze this Xiaohongshu creator's content strategy"

## Use cases

**For cross-border brands:**
- Monitor brand mentions and competitor activity on China's top discovery platform
- Understand what products Chinese consumers are excited about
- Find potential KOL/KOC partners by analyzing creator profiles and engagement

**For market researchers:**
- Track trending topics and consumer sentiment in China
- Analyze content strategies that work on Xiaohongshu
- Discover emerging product categories before they hit Western markets

**For developers:**
- Build Chinese market intelligence into your AI agents
- Create automated competitor monitoring dashboards
- Integrate Xiaohongshu data into your workflow

## How it compares

| Feature | xhs-mcp (this) | xpzouying/xiaohongshu-mcp |
|---------|-----------------|---------------------------|
| Language | TypeScript/Node | Go |
| Install | `npx` (1 second) | Docker + Chromium (minutes) |
| Dependencies | None | Docker, Chromium, ~500MB |
| Search | Yes | Yes |
| Read notes | Yes | Yes |
| User profiles | Yes | Yes |
| Publish content | Not yet | Yes |
| Login (QR code) | Not yet | Yes |
| Auth method | Cookie (manual) | Browser automation |

**This server is read-only by design.** It focuses on research and analysis. If you need to publish content, use [xpzouying/xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp) — it's excellent for that.

## Cookie notes

- Cookies typically last 7-30 days before expiring
- If you get `401` or `not_logged_in` errors, refresh your cookie
- The server will warn you at startup if `XHS_COOKIE` is not set
- Never commit your cookie to version control

## Roadmap

- [ ] Creator analytics (engagement rate calculation, posting frequency)
- [ ] Comment analysis (sentiment, themes)
- [ ] Trend detection (rising keywords over time)
- [ ] Content translation (Chinese → English summaries)
- [ ] Cookie refresh helper
- [ ] Publish support (opt-in, with rate limiting)

## Contributing

PRs welcome. This project is MIT licensed.

## About

Built by [Tristin](https://x.com/YinTristin) — building AI tools for cross-border commerce, in public.

---

*Xiaohongshu is a trademark of Xingyin Information Technology Co., Ltd. This project is not affiliated with or endorsed by Xiaohongshu.*