xiaohongshu-mcp-python

# Xiaohongshu MCP Python Project This is an automation tool for Xiaohongshu based on the Model Context Protocol (MCP), providing login, status checking, and content publishing functionalities. ## Features - Login Functionality - Supports QR code login for Xiaohongshu accounts - Status Check - Quickly check the current login status - Content Publishing - Automatically publish text and image content to Xiaohongshu - MCP Integration - Complete MCP server implementation that can integrate 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 use pip pip install -e . ``` ### Install Playwright Browser ```bash uv run playwright install chromium ``` ### Start in the Simplest Way (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: Standalone Command Line Tool #### 1. Login to Xiaohongshu ```bash # Login using GUI mode (recommended) uv run xiaohongshu-login # Login 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 main content" \ --images "image1.jpg" "image2.png" ``` ### Method 2: MCP Server Start the MCP server, which can integrate 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 start using the script uv run xiaohongshu-mcp-server ``` #### MCP Tool Description The server provides three MCP tools: 1. **xiaohongshu_login** - Login to Xiaohongshu account - headless: bool - Whether to use headless mode (default: False) - chrome_path: str - Path to Chrome (optional) 2. **xiaohongshu_check_status** - Check login status - headless: bool - Whether to use headless mode (default: True) - chrome_path: str - Path to Chrome (optional) 3. **xiaohongshu_publish** - Publish content - title: str - Title (required, <=40 characters) - content: str - Main content (required) - image_paths: List[str] - List of image paths (required) - headless: bool - Whether to use headless mode (default: False) - chrome_path: str - Path to Chrome (optional) ## Configuration Description ### Saving Login Status The login status is saved via cookies at: ``` ~/.xiaohongshu_mcp/cookies.json ``` ### Log Configuration MCP server logs are saved at: ``` 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 functionality module │ ├── login.py # Login functionality │ └── publish.py # Publishing functionality ├── server.py # MCP server ├── login.py # Login command line tool ├── check_status.py # Status check tool └── publish.py # Publish command line tool ``` ## Notes - It is recommended to use GUI mode for the publishing function to observe the publishing process. - The first use requires QR code login. - Image files must exist and be in the correct format. - Title length cannot exceed 40 characters. ## Troubleshooting ### Common Issues 1. **Login Failure** - Ensure the network connection is stable. - Try clearing cookies and logging in again. - Check if Chrome browser is installed correctly. 2. **Publishing Failure** - Confirm that you are logged in. - Check the image file paths and formats. - Validate the length of the title and content. 3. **MCP Server Startup Failure** - Ensure that the mcp[cli] dependency is installed. - Check the log file for detailed error information. ## Tech Stack - **Python 3.10+** - Primary development language - **Playwright** - Browser automation - **MCP Python SDK** - Model Context Protocol support - **Loguru** - Log management - **Pydantic** - Data validation - **uv** - Package manager ## License This project is open-sourced under the MIT License.