Content
# Tool List
This is an automation tool for Xiaohongshu based on the Model Context Protocol (MCP), providing login, status check, and content publishing functions.
## Features
- Login function - Supports scanning QR code to log in to Xiaohongshu account
- Status check - Quickly check the current login status
- Content publishing - Automatically publish graphic content to Xiaohongshu
- MCP integration - Complete MCP server implementation, can be integrated with AI clients (e.g., Cursor, Claude Code, Codex)
## Installation Requirements
- Python >= 3.10
- Chrome browser installed
- uv package manager (recommended)
## Quick Start
### Install dependencies
```bash
# Install using uv (recommended)
uv sync
# Or using pip
pip install -e .
```
### Install Playwright browser
```bash
uv run playwright install chromium
```
### Simple startup (development mode)
```bash
uv run mcp dev src/xiaohongshu_mcp/server.py
```
Equivalent production script startup method:
```bash
uv run xiaohongshu-mcp-server
```
## Usage
### Method 1: Independent command-line tool
#### 1. Log in to Xiaohongshu
```bash
# Log in using the interface mode (recommended)
uv run xiaohongshu-login
# Log in using headless mode
uv run xiaohongshu-login --headless
```
#### 2. Check login status
```bash
uv run xiaohongshu-status
```
#### 3. Publish content
```bash
uv run xiaohongshu-publish \
--title "My title" \
--content "This is the content" \
--images "image1.jpg" "image2.png"
```
### Method 2: MCP server
Start the MCP server, which can be integrated with AI clients that support the MCP protocol (e.g., Cursor, Claude Code, Codex):
```bash
# Start the development mode MCP server
uv run mcp dev src/xiaohongshu_mcp/server.py
# Or use a script to start
uv run xiaohongshu-mcp-server
```
#### MCP tool description
The server provides three MCP tools:
1. **xiaohongshu_login** - Log in to Xiaohongshu account
- headless: bool - Whether to use headless mode (default: False)
- chrome_path: str - Chrome path (optional)
2. **xiaohongshu_check_status** - Check login status
- headless: bool - Whether to use headless mode (default: True)
- chrome_path: str - Chrome path (optional)
3. **xiaohongshu_publish** - Publish content
- title: str - Title (required, <=40 characters)
- content: str - Content (required)
- image_paths: List[str] - Image path list (required)
- headless: bool - Whether to use headless mode (default: False)
- chrome_path: str - Chrome path (optional)
## Configuration Description
### Login status saving
The login status is saved in cookies:
```
~/.xiaohongshu_mcp/cookies.json
```
### Log configuration
MCP server logs are saved in:
```
logs/mcp_server.log
```
### Supported image formats
- JPG/JPEG
- PNG
- GIF
- WebP
### Project structure
```
src/xiaohongshu_mcp/
├── browser/ # Browser management module
│ ├── cookies.py # Cookie management
│ └── driver.py # Browser driver
├── xiaohongshu/ # Xiaohongshu function module
│ ├── login.py # Login function
│ └── publish.py # Publish function
├── server.py # MCP server
├── login.py # Login command-line tool
├── check_status.py # Status check tool
└── publish.py # Publish command-line tool
```
## Precautions
- The publishing function is recommended to use the interface mode for easy observation of the publishing process
- The first use requires scanning QR code to log in
- Image files must exist and have the correct format
- The title length cannot exceed 40 characters
## Troubleshooting
### Common issues
1. **Login failed**
- Ensure the network connection is normal
- Try clearing cookies and logging in again
- Check if the Chrome browser is installed correctly
2. **Publish failed**
- Confirm the logged-in status
- Check the image file path and format
- Verify the title and content length
3. **MCP server startup failed**
- Ensure the mcp[cli] dependency is installed
- Check the log file for detailed error information
## Technology stack
- **Python 3.10+** - Main development language
- **Playwright** - Browser automation
- **MCP Python SDK** - Model Context Protocol support
- **Loguru** - Log management
- **Pydantic** - Data verification
- **uv** - Package manager
## License
This project is open-sourced under the MIT license.