redbook

# Xiaohongshu Automatic Search and Comment Tool (MCP Server 2.0) <div align="right"> [English](README_EN.md) | 中文 </div> > This project is based on [JonaFly/RednoteMCP](https://github.com/JonaFly/RednoteMCP.git) and incorporates extensive practical experience for comprehensive optimization and feature expansion (by windsurf). I would like to express my sincere gratitude to the original author for their contributions! This is a Xiaohongshu automatic search and comment tool developed based on Playwright. As an MCP Server, it can be connected to an MCP Client (such as Claude for Desktop) through specific configurations to help users automatically complete operations such as logging into Xiaohongshu, searching for keywords, obtaining note content, and publishing AI-generated comments. ## Key Features and Advantages - **Deep Integration of AI Capabilities**: Leverages the large model capabilities of the MCP client (such as Claude) to generate more natural and relevant comment content. - **Modular Design**: Divides functionalities into three independent modules: note analysis, comment generation, and comment posting, enhancing code maintainability. - **Powerful Content Acquisition**: Integrates multiple methods for acquiring note content, ensuring complete retrieval of various note titles, authors, and body content. - **Persistent Login**: Uses persistent browser contexts, eliminating the need for repeated logins after the initial login. - **Two-Step Commenting Process**: First, obtains note analysis results, then generates and publishes comments via the MCP client. ## Main Optimizations in Version 2.0 - **Enhanced Content Acquisition**: Refactored the note content acquisition module, adding page load wait times and scrolling operations to implement four different content acquisition methods. - **AI Comment Generation**: Refactored the commenting feature to return note analysis results to the MCP client, allowing the client's AI capabilities to generate more natural and relevant comments. - **Functional Modularization**: Divided functionalities into three independent modules: note analysis, comment generation, and comment posting, enhancing code maintainability. - **Search Result Optimization**: Resolved the issue of titles not displaying in search results, providing more complete search results. - **Enhanced Error Handling**: Added more detailed error handling and debugging information output. ## I. Core Features ### 1. User Authentication and Login - **Persistent Login**: Supports manual QR code login, saving the login state after the first login, eliminating the need for repeated QR code scans in subsequent uses. - **Login Status Management**: Automatically detects login status and prompts the user to log in when necessary. ### 2. Content Discovery and Acquisition - **Intelligent Keyword Search**: Supports multi-keyword search, allows specifying the number of returned results, and provides complete note information. - **Multi-Dimensional Content Acquisition**: Integrates four different acquisition methods to ensure accurate retrieval of note titles, authors, publication times, and body content. - **Comment Data Acquisition**: Supports acquiring note comment content, including commenter, comment text, and time information. ### 3. Content Analysis and Generation - **Note Content Analysis**: Automatically analyzes note content, extracts key information, and identifies the note's domain. - **AI Comment Generation**: Leverages the AI capabilities of the MCP client (such as Claude) to generate natural and relevant comments based on note content. - **Multi-Type Comment Support**: Supports four different types of comment generation: - **Traffic-Driving**: Guides users to follow or send private messages. - **Praise-Oriented**: Simple interaction to gain favor. - **Inquiry-Based**: Increases interaction in the form of questions. - **Professional**: Demonstrates professional knowledge to establish authority. ### 4. Data Return and Feedback - **Structured Data Return**: Returns note analysis results to the MCP client in JSON format, facilitating AI comment generation. - **Comment Posting Feedback**: Provides real-time feedback on comment posting results. ## II. Installation Steps 1. **Python Environment Preparation**: Ensure that Python 3.8 or later is installed on your system. If not installed, you can download and install it from the official Python website. 2. **Project Acquisition**: Clone or download this project to your local machine. 3. **Create a Virtual Environment**: Create and activate a virtual environment in the project directory (recommended): ```bash # Create a virtual environment python3 -m venv venv # Activate the virtual environment # Windows venv\Scripts\activate # macOS/Linux source venv/bin/activate ``` 4. **Install Dependencies**: Install the required dependencies in the activated virtual environment: ```bash pip install -r requirements.txt pip install fastmcp ``` 5. **Install Browser**: Install the browser required by Playwright: ```bash playwright install ``` ## III. MCP Server Configuration Add the following content to the configuration file of the MCP Client (such as Claude for Desktop) to configure this tool as an MCP Server: ### Mac Configuration Example ```json { "mcpServers": { "xiaohongshu MCP": { "command": "/absolute/path/to/venv/bin/python3", "args": [ "/absolute/path/to/xiaohongshu_mcp.py", "--stdio" ] } } } ``` ### Windows Configuration Example ```json { "mcpServers": { "xiaohongshu MCP": { "command": "C:\\Users\\username\\Desktop\\MCP\\Redbook-Search-Comment-MCP2.0\\venv\\Scripts\\python.exe", "args": [ "C:\\Users\\username\\Desktop\\MCP\\Redbook-Search-Comment-MCP2.0\\xiaohongshu_mcp.py", "--stdio" ] } } } ``` > **Important Notes**: > - Use the **full absolute path** of the Python interpreter in the virtual environment. > - Mac example: `/Users/username/Desktop/RedBook-Search-Comment-MCP/venv/bin/python3` > - Windows example: `C:\Users\username\Desktop\MCP\Redbook-Search-Comment-MCP2.0\venv\Scripts\python.exe` > - Similarly, xiaohongshu_mcp.py also needs to use the **full absolute path**. > - Backslashes in Windows paths need to be double-escaped in JSON (using `\\`). ### Python Command Differentiation (python vs python3) In different system environments, Python commands may vary depending on your system configuration. Here's how to determine which command you should use: 1. **Determine Your Python Command**: - Run `python --version` and `python3 --version` in the terminal. - See which command returns Python 3.x version (this project requires Python 3.8+). 2. **Confirm in the Virtual Environment**: - After activating the virtual environment, run `which python` or `where python` (Windows). - This will display the full path to the Python interpreter. 3. **Use the Correct Command in the Configuration**: - Mac: Usually `python3` or `python` in the virtual environment. - Windows: Usually `python` or `python.exe`. In the configuration file, always use the **full absolute path** of the Python interpreter in the virtual environment, not the command name. ## IV. Usage ### (I) Starting the Server 1. **Directly Run**: In the project directory, activate the virtual environment and execute: ```bash python3 xiaohongshu_mcp.py ``` 2. **Start via MCP Client**: After configuring the MCP Client, follow the client's operation flow to start and connect. ### (II) Main Function Operations After connecting to the server in the MCP Client (such as Claude for Desktop), you can use the following functions: ### 1. Login to Xiaohongshu **Tool Function**: ``` mcp0_login() ``` **Usage in MCP Client**: Send the following text directly: ``` Help me log in to my Xiaohongshu account. ``` Or: ``` Please log in to Xiaohongshu. ``` **Function Description**: The first time you use it, it will open a browser window and wait for the user to manually scan the QR code to log in. After successful login, the tool will save the login status. ### 2. Search Notes **Tool Function**: ``` mcp0_search_notes(keywords="keywords", limit=5) ``` **Usage in MCP Client**: Send a search request containing keywords: ``` Help me search for Xiaohongshu notes with the keyword: food. ``` Specify the number of results to return: ``` Help me search for Xiaohongshu notes with the keyword travel and return 10 results. ``` **Function Description**: Searches Xiaohongshu notes based on keywords and returns the specified number of results. The default is to return 5 results. ### 3. Get Note Content **Tool Function**: ``` mcp0_get_note_content(url="Note URL") ``` **Usage in MCP Client**: Send a request containing the note URL: ``` Help me get the content of this note: https://www.xiaohongshu.com/search_result/xxxx ``` Or: ``` Please view the content of this Xiaohongshu note: https://www.xiaohongshu.com/search_result/xxxx ``` **Function Description**: Gets the detailed content of the specified note URL, including the title, author, publication time, and body content. ### 4. Get Note Comments **Tool Function**: ``` mcp0_get_note_comments(url="Note URL") ``` **Usage in MCP Client**: Send a comment request containing the note URL: ``` Help me get the comments of this note: https://www.xiaohongshu.com/search_result/xxxx ``` Or: ``` Please view the comment section of this Xiaohongshu note: https://www.xiaohongshu.com/search_result/xxxx ``` **Function Description**: Gets the comment information of the specified note URL, including the commenter, comment content, and comment time. ### 5. Post Smart Comment **Tool Function**: ``` mcp0_post_smart_comment(url="Note URL", comment_type="Comment Type") ``` **Usage in MCP Client**: Send a request containing the note URL and comment type: ``` Help me write a [type] comment for this note: https://www.xiaohongshu.com/explore/xxxx ``` **Function Description**: Gets the note analysis results and returns them to the MCP client, which generates the comment and calls post_comment to publish it. ### 6. Post Comment **Tool Function**: ``` mcp0_post_comment(url="Note URL", comment="Comment Content") ``` **Usage in MCP Client**: Send a request containing the note URL and comment content: ``` Help me post this comment to the note: https://www.xiaohongshu.com/explore/xxxx Comment content: [Comment Content] ``` **Function Description**: Publishes the specified comment content to the note page. ## IV. User Guide ### 0. Working Principle This tool uses a two-step process to implement smart commenting: 1. **Note Analysis**: Call the `post_smart_comment` tool to get note information (title, author, content, etc.). 2. **Comment Generation and Posting**: - The MCP client (such as Claude) generates comments based on the note analysis results. - Call the `post_comment` tool to publish the comment. This design fully utilizes the AI capabilities of the MCP client, enabling more natural and relevant comment generation. ### 1. Usage in MCP Client #### Basic Operations | Function | Example Command | |---------|----------| | **Search Notes** | `Help me search for Xiaohongshu notes about [keywords].` | | **Get Note Content** | `Help me view the content of this Xiaohongshu note: https://www.xiaohongshu.com/explore/xxxx` | | **Analyze Note** | `Help me analyze this Xiaohongshu note: https://www.xiaohongshu.com/explore/xxxx` | | **Get Comments** | `Help me view the comments of this note: https://www.xiaohongshu.com/explore/xxxx` | | **Generate Comment** | `Help me write a [type] comment for this Xiaohongshu note: https://www.xiaohongshu.com/explore/xxxx` | #### Comment Type Options | Type | Description | Applicable Scenarios | |---------|------|----------| | **Traffic-Driving** | Guides users to follow or send private messages. | Increase followers or private message interactions. | | **Praise-Oriented** | Simple interaction to gain favor. | Increase exposure and interaction rate. | | **Inquiry-Based** | Increases interaction in the form of questions. | Trigger blogger replies, increasing interaction depth. | | **Professional** | Demonstrates professional knowledge to establish authority. | Establish a professional image and enhance credibility. | ### 2. Example of Actual Workflow ``` User: Help me write a professional comment for this Xiaohongshu note: https://www.xiaohongshu.com/explore/xxxx Claude: I will help you write a professional comment. Let me get the note content and generate a comment. [Calling post_smart_comment tool] # The tool returns note analysis results, including title, author, content, domain, and keywords. Claude: I have obtained the note information. This is a note about [topic]. Based on the content, I have generated and posted the following professional comment: "[Generated professional comment content]" [Calling post_comment tool] Claude: The comment has been successfully posted! ``` **Note**: In the above process, the `post_smart_comment` tool is only responsible for obtaining the note analysis results and returning them to the MCP client. The actual comment generation is done by the MCP client (such as Claude) itself. ### 3. Working Principle The new version of the Xiaohongshu MCP tool adopts a modular design, divided into three core modules: 1. **Note Analysis Module** (analyze_note) - Get the note's title, author, publication time, and content. - Analyze the note's domain and keywords. - Return structured note information. 2. **Comment Generation Module** (implemented by the MCP client) - Receive note analysis results. - Generate natural and relevant comments based on the note content and comment type. - Allow users to preview and modify comments before posting. 3. **Comment Posting Module** (post_comment) - Receive the generated comment content. - Locate and operate the comment input box. - Post the comment and return the result. ## V. Code Structure - **xiaohongshu_mcp.py**: The core file that implements the main functions, including the code logic for login, search, get content and comments, and post comments. - **requirements.txt**: Records the dependency libraries required by the project. ## VI. Common Issues and Solutions 1. **Connection Failure**: - Make sure you are using the **full absolute path** of the Python interpreter in the virtual environment. - Make sure the MCP server is running. - Try restarting the MCP server and client. 2. **Browser Session Issues**: If you encounter a `Page.goto: Target page, context or browser has been closed` error: - Restart the MCP server. - Reconnect and log in. 3. **Dependency Installation Issues**: If you encounter a `ModuleNotFoundError` error: - Make sure all dependencies are installed in the virtual environment. - Check if the fastmcp package is installed. ## VII. Precautions and Troubleshooting ### 1. Usage Precautions - **Browser Mode**: The tool runs in Playwright's non-headless mode, which opens a real browser window during runtime. - **Login Method**: The first login requires manual QR code scanning. If the login status is valid for subsequent use, you do not need to scan the QR code again. - **Platform Rules**: Please strictly abide by the relevant regulations of the Xiaohongshu platform during use, avoid excessive operations, and prevent the account from facing the risk of being banned. - **Comment Frequency**: It is recommended to control the comment posting frequency, avoid posting a large number of comments in a short period of time, and the number of comments posted per day should not exceed 30. ### 2. Common Issues and Solutions #### Browser Instance Issues If you encounter errors similar to "Page.goto: Target page, context or browser has been closed", it may be that the browser instance was not closed correctly or there is a data directory lock file issue. Please try: ```bash # Delete the browser lock file rm -f /project/path/browser_data/SingletonLock /project/path/browser_data/SingletonCookie # If the problem persists, back up and rebuild the browser data directory mkdir -p /project/path/backup_browser_data mv /project/path/browser_data/* /project/path/backup_browser_data/ mkdir -p /project/path/browser_data ``` #### Content Acquisition Issues If you cannot get the note content or the content is incomplete, you can try: 1. **Increase Wait Time**: Xiaohongshu note pages may require longer loading times, especially notes containing a large number of pictures or videos. 2. **Clear Browser Cache**: Sometimes browser cache can affect content acquisition. 3. **Try Different Acquisition Methods**: The tool integrates multiple acquisition methods. If one method fails, you can try other methods. #### Platform Change Adaptation The Xiaohongshu platform may update the page structure and DOM elements, causing the tool to not work properly. If you encounter such problems: 1. **Check for Project Updates**: Pay attention to the latest version of the project and update it in time. 2. **Adjust Selectors**: If you are familiar with the code, you can try adjusting CSS selectors or XPath expressions. 3. **Submit Problem Feedback**: Submit the problem to the project maintainer, describing the specific problem and page changes encountered. ## VIII. Disclaimer This tool is for learning and research purposes only. Users should strictly abide by relevant laws and regulations and the regulations of the Xiaohongshu platform. The developers of this project are not responsible for any problems caused by improper use.