xiaohongshu-mcp-server

A Model Context Protocol (MCP) server for Xiaohongshu (Little Red Book) - China's leading lifestyle social media platform.

Publish image notes, search content, view note details, and manage your account - all through MCP tools that AI assistants can use directly.

How It Works

Uses Playwright to run a headless Chromium browser that:

Loads your XHS session cookies
Generates authentic API signatures via the XHS web app's built-in signing function
Makes API calls through the browser's network context (bypasses anti-bot detection)
Uploads images directly to XHS CDN

No browser automation of UI elements - all interactions go through XHS's internal API.

Tools

Tool	Description
`check_login_status`	Check if you're logged in
`get_login_qrcode`	Generate QR code for login
`check_qrcode_status`	Poll QR scan status & save session
`reload_cookies`	Reload cookies from disk
`publish_content`	Publish an image note with title, text, images, and tags
`search_feeds`	Search XHS notes by keyword
`get_feed_detail`	Get full details of a note
`user_profile`	Get user profile information

Installation

Terminal

pip install xiaohongshu-mcp-server
playwright install chromium

For QR code image generation (optional):

Terminal

pip install "xiaohongshu-mcp[qrcode]"

Quick Start

1. Start the server

HTTP mode (for Claude Code, Cursor, etc.):

bash

xhs-mcp --transport http --port 18060

stdio mode (for Claude Desktop):

bash

xhs-mcp --transport stdio

2. Login

Call the get_login_qrcode tool, scan the QR code with the Xiaohongshu app, then call check_qrcode_status with the returned qr_id and code. Cookies are saved to ~/.xhs-mcp/cookies.json and persist across restarts.

3. Use

Ask your AI assistant to publish a note, search for content, etc.

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

config.json

{
  "mcpServers": {
    "xhs-mcp": {
      "command": "xhs-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Claude Code

Terminal

claude mcp add xhs-mcp --transport http http://localhost:18060/mcp

Then start the server: xhs-mcp

As a LaunchAgent (macOS auto-start)

Create ~/Library/LaunchAgents/com.xhs-mcp.plist:

xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.xhs-mcp</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/your/venv/bin/xhs-mcp</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/xhs-mcp.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/xhs-mcp.err</string>
</dict>
</plist>

bash

launchctl load ~/Library/LaunchAgents/com.xhs-mcp.plist

Example: Publish a Note

python

# Via MCP tool call
publish_content(
    title="Hello XHS!",
    content="My first post published via MCP.",
    images=["/path/to/photo.jpg"],
    tags=["MCP", "AI"]
)

Requirements

Python 3.12+
Chromium (installed via playwright install chromium)
A Xiaohongshu account

License

MIT