xhs-mcp 🍠

An MCP server that lets your AI agent publish notes to Xiaohongshu (RedNote / 小红书) automatically using Playwright browser automation.

Features

📸 Publish photo notes with title, body, and image
🤖 MCP-compatible — works with Claude, Cursor, and any MCP-supported agent
🔐 Session persistence — log in once, post forever
🧠 Human-like typing to avoid bot detection

Requirements

Python 3.10+
macOS (tested on macOS with Apple Silicon)

Installation

1. Clone the repo

git clone https://github.com/FrancoSbaffi/xhs-mcp.git
cd xhs-mcp

2. Install dependencies

pip install -r requirements.txt

3. Install Chromium

python -m playwright install chromium

4. Set up your session (first time only)

Run the login script and log in manually in the browser that opens:

python post.py

Once logged in, press ENTER in the terminal. Your session will be saved to session/auth.json.

Usage

Option A — Run standalone

Edit content/texto.txt with your post content (first line = title, rest = body). Add your image as content/imagen.jpg. Then run:

python post.py

Option B — Use as MCP server with Claude

Add this to your Claude MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "xiaohongshu": {
      "command": "python3.11",
      "args": ["/absolute/path/to/xhs-mcp/server.py"]
    }
  }
}

Then in Claude, you can say:

"Post this to my Xiaohongshu: title 'Hello World', body 'This is my first automated post', image at /path/to/image.jpg"

MCP Tool Reference

post_note

| Parameter | Type | Description | |---|---|---| | title | string | Post title (max 20 characters) | | body | string | Post body text | | image_path | string | Absolute path to image (jpg/png) |

Project Structure

xhs-mcp/
├── post.py          # Standalone posting script
├── server.py        # MCP server
├── requirements.txt # Dependencies
├── content/         # Default content folder
│   ├── texto.txt    # Post text (title on first line)
│   └── imagen.jpg   # Post image
└── session/         # Saved login session (git ignored)
    └── auth.json

Important Notes

⚠️ This project uses browser automation and is not affiliated with Xiaohongshu
⚠️ Use responsibly — avoid posting at high frequency
⚠️ Session may expire and require re-login
🔒 Never commit session/auth.json to GitHub — it contains your login credentials

.gitignore

Make sure to add this before pushing:

session/
.env

License

MIT

MCP Servers