Content
# Tool List
A universal Xiaohongshu (Little Red Book) MCP Server, enabling [Claude Code](https://claude.ai/claude-code) to search, read, and analyze any content on Xiaohongshu.
## What It Can Do
Driven by natural language instructions, such as:
```
"Help me check the experience posts about London housing on Xiaohongshu and summarize what to note"
"Analyze the real reviews of iPhone 17 on Xiaohongshu"
"Is this Xiaohongshu account a real person or a marketing account? Check it for me"
"What are the recent discussions about KCL CSC scholarships on Xiaohongshu?"
```
Claude Code will automatically plan the query strategy, call MCP tools to collect data, analyze content, and output conclusions.
## Architecture
```
User Natural Language Instructions
│
▼
Claude Code (Read Skill → Plan Strategy)
│
├── Call ──→ xhs-mcp Server (Local Run)
│ ├─ xhs_search Search Notes
│ ├─ xhs_detail Note Details + Comments
│ ├─ xhs_creator Author Homepage + History Posts
│ ├─ xhs_login Login Management
│ └─ xhs_status Service Status
│ │
│ └─ Underlying: Playwright Signature + httpx Request
│
├── Own Ability ──→ Content Analysis, Classification, Summary, Judgment
│
└── Output ──→ Terminal Display / Structured Report
```
## Prerequisites
- Python 3.10+
- [Claude Code CLI](https://claude.ai/claude-code)
- Chromium Browser (Playwright will install automatically)
## Installation
```bash
# 1. Clone Repository
git clone https://github.com/haoyu-haoyu/xhs-mcp.git
cd xhs-mcp
# 2. Install Python Dependencies
pip install mcp playwright httpx tenacity xhshow
# 3. Install Playwright Browser
playwright install chromium
```
## Configure Claude Code
Create `.mcp.json` in the project root directory or `~/.claude/`:
```json
{
"mcpServers": {
"xhs": {
"command": "python3",
"args": ["<your_path>/xhs-mcp/server.py"],
"cwd": "<your_path>/xhs-mcp",
"env": {}
}
}
}
```
Replace `<your_path>` with the actual path.
### Install Skill (Optional but Recommended)
Copy `SKILL.md` to Claude Code's commands directory:
```bash
mkdir -p ~/.claude/commands
cp SKILL.md ~/.claude/commands/xhs.md
```
Then, input `/xhs` in Claude Code to activate Xiaohongshu analysis capability.
## First Use: Login
Xiaohongshu API requires a valid Cookie. Scan the QR code to log in for the first use:
1. Say in Claude Code: `"Help me log in to Xiaohongshu"` or call `xhs_login(action="qrcode")`
2. A browser window will pop up displaying the QR code
3. Scan the QR code with the Xiaohongshu App to confirm
4. Cookie will be saved automatically, valid for about 7-30 days
You can also import a Cookie string manually (copy from browser developer tools):
```
xhs_login(action="cookie_str", cookie_str="your_cookie_string")
```
## MCP Tool Description
### `xhs_search` — Search Notes
| Parameter | Type | Default Value | Description |
|------|------|--------|------|
| `keywords` | `list[str]` | *Required* | Search keyword list |
| `sort` | `str` | `"general"` | `general` / `time_descending` / `popularity_descending` |
| `page` | `int` | `1` | Page number |
| `note_type` | `int` | `0` | `0`=All `1`=Image and Text `2`=Video |
| `force_refresh` | `bool` | `false` | Bypass cache |
Returns a list containing `note_id`, `xsec_token`, title, summary, interaction data, and author information.
### `xhs_detail` — Get Note Details and Comments
| Parameter | Type | Default Value | Description |
|------|------|--------|------|
| `note_ids` | `list[str]` | *Required* | Note ID list (from search results) |
| `xsec_tokens` | `list[str]` | *Required* | Security token list (from search results) |
| `get_comments` | `bool` | `false` | Whether to get comments |
| `comment_count` | `int` | `20` | Number of comments to get per note |
| `force_refresh` | `bool` | `false` | Bypass cache |
Returns complete text, image list, topic tags, IP location, and comments (including sub-comments).
### `xhs_creator` — View Author Homepage
| Parameter | Type | Default Value | Description |
|------|------|--------|------|
| `user_ids` | `list[str]` | *Required* | User ID list |
| `note_count` | `int` | `5` | Number of recent posts to get |
| `force_refresh` | `bool` | `false` | Bypass cache |
Returns profile, number of followers, likes and collections, IP location, certification tags, and recent posts.
### `xhs_login` — Login Management
| Parameter | Type | Default Value | Description |
|------|------|--------|------|
| `action` | `str` | `"check"` | `check` / `qrcode` / `cookie_str` |
| `cookie_str` | `str` | `""` | `cookie_str` action parameter |
### `xhs_status` — Service Status
No parameters. Returns browser connection status, Cookie validity, cache entry count, and size.
## Cache Strategy
| Data Type | TTL | Description |
|----------|-----|------|
| Search Results | 15 minutes | Cache by keyword + sort + page combination |
| Note Details | 24 hours | Cache by note_id |
| Author Information | 7 days | Cache by user_id |
All tools support `force_refresh: true` to bypass cache and get the latest data. Cache files are stored in the `cache/` directory and will not be uploaded to Git.
## ⚠️ Security Notice: Cookie Stored in Plain Text
After successful login, Xiaohongshu Cookie will be written to the `config/cookies.json` plain text JSON file. These Cookies **are equivalent to your account credentials** - whoever obtains them can operate your account with them.
Repository's mitigation measures:
- Write file permissions set to `0600` (only current user readable and writable, POSIX system)
- Load will detect and correct overly broad permissions
- `.gitignore` excludes `config/cookies.json`, which will not be submitted unexpectedly
**However, you still need to pay attention to:**
- **Do not use this tool on shared computers** (labs / public devices / cloud sandbox), root users can still read
- **Backup / synchronization tools** (iCloud Drive, Dropbox, Time Machine) may copy plain text Cookies to other locations
- **On Windows, `os.chmod()` can only switch read-only bits**, other Unix permission bits are ignored; real access control comes from NTFS ACL, which requires you to manually limit file permissions in the resource manager
⚠️ **Note**: `xhs_login`'s `cookie_str` method **will still write the imported Cookie to `config/cookies.json`** (no pure memory mode currently). Regardless of where you read the cookie string, as long as you call this tool, it will be written to the local disk. If you don't want to write to disk, you need to patch `xhs/login.py`'s `login_by_cookie_str` and remove the `save_cookies_to_cache()` call.
## Project Structure
```text
xhs-mcp/
├── server.py # MCP Server entry, register tools and dispatch
├── xhs/
│ ├── handlers.py # Business logic of 5 MCP tools (can be tested separately)
│ ├── client.py # XHS API client (signature + request)
│ ├── sign.py # Request signature (X-S, X-T, x-S-Common)
│ ├── browser.py # Playwright browser management
│ ├── login.py # Login process (QR code / Cookie import)
│ ├── cache.py # File cache system
│ ├── models.py # Data model and exception definition
│ └── stealth.min.js # Anti-headless browser detection script (released with wheel)
├── config/
│ └── settings.py # Configuration constants
├── tests/ # Unit tests (pytest + pytest-asyncio)
├── SKILL.md # Claude Code Skill definition
└── pyproject.toml
```
## Technical Details
- **Signature Mechanism**: Inject page environment through Playwright, call Xiaohongshu front-end's `window._webmsxyw` function to generate signature headers (X-S, X-T), and then construct x-S-Common and X-B3-Traceid with Python
- **Anti-detection**: Inject `stealth.min.js` to prevent headless browser detection
- **Request Frequency**: Built-in 2-5 second random interval, 5-10 second interval for multi-keyword search
- **Error Handling**: All errors return structured JSON, will not cause MCP Server to crash. Supports 3 automatic retries
## Acknowledgements
Core collection capabilities extracted and refactored from [MediaCrawler](https://github.com/NanmiCoder/MediaCrawler), thanks to the original author's open-source contributions.
## License
Non-Commercial Learning Use Only.
This project depends on Xiaohongshu's non-public API, please comply with Xiaohongshu's service terms. Users are responsible for their own usage behavior.
