# 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
```bash
git clone https://github.com/FrancoSbaffi/xhs-mcp.git
cd xhs-mcp
```

### 2. Install dependencies
```bash
pip install -r requirements.txt
```

### 3. Install Chromium
```bash
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:
```bash
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:
```bash
python post.py
```

### Option B — Use as MCP server with Claude

Add this to your Claude MCP config (`claude_desktop_config.json`):
```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