Automated Xiaohongshu Interaction Toolkit (MCP Server Implementation)

This repository is an enhanced iteration of the foundational work by JonaFly/RednoteMCP, refined through practical application and optimization (contributor: windsurf). Deep appreciation is extended to the original author for the initial framework.

This system, built upon the Playwright automation library, functions as an MCP Server endpoint. It facilitates automated operations on the Xiaohongshu platform, encompassing secure sign-in, executing specified keyword searches, extracting complete note data, and deploying sophisticated, context-aware replies via leveraging external MCP clients (like Claude for Desktop).

Notice: Version 2.0 of Redbook-Search-Comment-MCP is now available! Please navigate there for the latest release.

Key Upgrades in V2.0: - Rectified an issue where note titles were omitted during result retrieval. - Introduced multiple mechanisms to ensure comprehensive extraction of note content. - Complete redesign of the commenting subsystem, integrating AI capabilities from the MCP client (e.g., Claude) for producing highly organic responses. - Modularization of core functionalities into distinct components: Content Analysis, Comment Generation, and Comment Submission.

I. Core Capabilities

• Automated Authentication: Supports QR code scanning for initial access. Once successfully authenticated, session persistence is maintained for subsequent, non-interactive logins.
• Keyword Retrieval: Executes searches on Xiaohongshu using user-defined keywords, with configurable output limits.
• Asset Extraction (Note Body): Accepts a note's unique URL to retrieve its full textual and media content.
• Comment Data Harvesting: Fetches existing comment threads associated with a given note URL.
• Intelligent Reply Deployment: Facilitates several strategic comment categories: Promotion (driving traffic/DMs), Engagement (simple positive interaction), Inquiry (prompting dialogue), and Expertise (establishing authority). Selections are based on operational requirements.

II. Deployment Procedure

1. Prerequisites (Python): Ensure a Python environment, version 3.8 or newer, is installed on the host system. Installation binaries are available on the official Python website.

2. Source Acquisition: Clone or download the project repository to your local filesystem.

3. Environment Setup: Establish and activate a dedicated virtual environment within the project directory (strongly recommended): bash # Virtual environment creation python3 -m venv venv

# Activation (Windows) venv\Scripts\activate # Activation (macOS/Linux) source venv/bin/activate

1. Dependency Installation: With the virtual environment active, install required libraries: bash pip install -r requirements.txt pip install fastmcp

2. Browser Engine Preparation: Install the necessary browser binaries managed by Playwright: bash playwright install

III. MCP Server Configuration

Configure your MCP Client's settings file (e.g., for Claude for Desktop) by integrating this tool as an intermediary server:

{ "mcpServers": { "xiaohongshu MCP": { "command": "/absolute/path/to/venv/bin/python3", "args": [ "/absolute/path/to/xiaohongshu_mcp.py", "--stdio" ] } } }

Critical Note: - The full absolute path to the Python interpreter within your virtual environment must be used. - Example: /Users/username/Desktop/RedBook-Search-Comment-MCP/venv/bin/python3 - Likewise, the path to xiaohongshu_mcp.py must also be specified absolutely.

IV. Operational Guide

(A) Initiating the Server

1. Direct Execution: From the project directory, after environment activation, run: bash python3 xiaohongshu_mcp.py

2. Client-Initiated Launch: Once the MCP Client configuration is finalized, start the server using the established connection protocol within the client application.

(B) Primary Function Invocation

After establishing a connection via the MCP Client to the running server, use the following interactions:

1. Xiaohongshu Login

Tool Signature:

mcp0_login()

Client Prompt Examples:

Initiate login sequence for my Xiaohongshu account

or

Please authenticate on Redbook.

Functionality Overview: Opens a browser instance requiring manual QR code scanning for the first run. Successful credentials are saved for session reuse.

2. Content Search

Tool Signature:

mcp0_search_notes(keywords="term", limit=5)

Client Prompt Examples:

Find Xiaohongshu notes matching the term: Culinary Delights

Specify result count:

Search for travel-related notes and return exactly 10 entries.

Functionality Overview: Queries the platform based on provided keywords, returning up to the specified number of results (default is 5).

3. Note Content Retrieval

Tool Signature:

mcp0_get_note_content(url="Note URL")

Client Prompt Examples:

Extract the full content for this post URL: https://www.xiaohongshu.com/search_result/xxxx

or

Review the details of the Redbook note located at: https://www.xiaohongshu.com/search_result/xxxx

Functionality Overview: Retrieves comprehensive data for a specific note ID, including headline, author metadata, timestamps, and main body text.

4. Comment Extraction

Tool Signature:

mcp0_get_note_comments(url="Note URL")

Client Prompt Examples:

Retrieve all comments associated with this note: https://www.xiaohongshu.com/search_result/xxxx

or

Show me the feedback section for URL: https://www.xiaohongshu.com/search_result/xxxx

Functionality Overview: Fetches the entire comment thread for a given note URL, detailing commenters, their text, and posting times.

5. Smart Comment Posting

Tool Signature:

mcp0_post_smart_comment(url="Note URL", comment_type="Reply Category")

Client Prompt Examples:

Post a 'Professional' style response on this note: https://www.xiaohongshu.com/search_result/xxxx

or

Deploy a 'Promotional' comment under the link: https://www.xiaohongshu.com/search_result/xxxx

Acceptable Comment Types (Parameter Values): - "引流" (Promotion): Designed to encourage follows or direct messages. - "点赞" (Engagement): Basic, positive interaction to build rapport. - "咨询" (Inquiry): Formulated as a question to increase thread activity. - "专业" (Expertise): Content crafted to demonstrate specialized knowledge.

Functionality Overview: Posts an AI-generated reply under the specified note. The generated text is tailored both to the note's subject matter and the chosen strategic comment type.

V. System Architecture Overview

• xiaohongshu_mcp.py: The central execution script containing the implementation logic for all exposed functionalities (login, search, data fetch, comment management).
• requirements.txt: A manifest file detailing all necessary external Python package dependencies.

VI. Troubleshooting Common Issues

1. Connection Failure:
2. Verify that the absolute path provided for the Python executable is precise.
3. Confirm the MCP Server process is actively running.

4. Attempt sequential restarts of both the server and the connecting client.

5. Browser Session Loss: If encountering errors like Page.goto: Target page, context or browser has been closed:

6. Terminate and restart the MCP server.

7. Re-establish the connection and perform a fresh login.

8. Installation Errors: If ModuleNotFoundError exceptions occur:

9. Double-check that all listed dependencies were installed within the correct active virtual environment.
10. Ensure the fastmcp package is successfully installed.

VII. Operational Guidelines

• Browser Visibility: The tool operates Playwright in non-headless mode by default, meaning user interaction will be visible via a standard browser window.
• Session Handling: Initial setup requires manual QR code authentication. Subsequent access relies on preserved session cookies, bypassing repeated logins unless the session expires or is cleared.
• Platform Compliance: Users must scrupulously adhere to Xiaohongshu's Terms of Service. Excessive or automated activity risks account suspension.
• Evolving Compatibility: As Xiaohongshu frequently updates its front-end structure, the reliability of search results and comment features may fluctuate. Monitor project updates or contact developers for resolution if functionality degrades.

VIII. Legal Disclaimer

This toolkit is provided strictly for educational exploration and research purposes. Users are mandated to comply with all applicable laws and the regulations set forth by the Xiaohongshu platform. The creators of this project assume no liability for any adverse outcomes resulting from the improper utilization of this software.

WIKIPEDIA: A headless browser is a web browser without a graphical user interface. Headless browsers provide automated control of a web page in an environment similar to popular web browsers, but they are executed via a command-line interface or using network communication. They are particularly useful for testing web pages as they are able to render and understand HTML the same way a browser would, including styling elements such as page layout, color, font selection and execution of JavaScript and Ajax which are usually not available when using other testing methods. Since version 59 of Google Chrome and version 56 of Firefox, there is native support for remote control of the browser. This made earlier efforts obsolete, notably PhantomJS.

== Use cases == The main use cases for headless browsers are:

Test automation in modern web applications (web testing) Taking screenshots of web pages. Running automated tests for JavaScript libraries. Automating interaction of web pages.

=== Other uses === Headless browsers are also useful for web scraping. Google stated in 2009 that using a headless browser could help their search engine index content from websites that use Ajax. Headless browsers have also been misused in various ways:

Perform DDoS attacks on web sites. Increase advertisement impressions. Automate web sites in unintended ways e.g. for credential stuffing. However, a study of browser traffic in 2018 found no preference by malicious actors for headless browsers. There is no indication that headless browsers are used more frequently than non-headless browsers for malicious purposes, like DDoS attacks, SQL injections or cross-site scripting attacks.

== Usage == As several major browsers natively support headless mode through APIs, some software exists to perform browser automation through a unified interface. These include:

Selenium WebDriver – a W3C compliant implementation of WebDriver Playwright – a Node.js library to automate Chromium, Firefox and WebKit Puppeteer – a Node.js library to automate Chrome or Firefox

=== Test automation === Some test automation software and frameworks include headless browsers as part of their testing apparati.

Capybara uses headless browsing, either via WebKit or Headless Chrome to mimic user behavior in its testing protocols. Jasmine uses Selenium by default, but can use WebKit or Headless Chrome, to run browser tests. Cypress, a frontend testing framework QF-Test, a software tool for automated testing of programs via the graphical user interface where a headless browser can also be used for testing.

=== Alternatives === Another approach is to use software that provides browser APIs. For example, Deno provides browser APIs as part of its design. For Node.js, jsdom is the most complete provider. While most are able to support common browser features (HTML parsing, cookies, XHR, some JavaScript, etc.), they do not render the DOM and have limited support for DOM events. They usually perform faster than