java-xiaohongshu

This MCP server provides a Java-based Xiaohongshu automation service built on Spring Boot, Playwright Java, and the MCP protocol. It exposes standard MCP operations such as login, posting image-text content, video content, searching posts, fetching a home/recommendation feed, retrieving post details with interactions and comments, automated commenting, and accessing user profile data. The service can be integrated with AI agents and MCP clients for automated workflows, content publishing, and data collection. You can run it directly as a CLI Java app or deploy it via Docker for containerized usage. After starting, the MCP endpoint is exposed at /mcp and can be consumed by MCP clients using the standard MCP contract defined in the repository.

Prerequisites:

• Java 21 (or a compatible JDK)
• Maven for building the JAR (optional if using the prebuilt Docker image)
• Docker (for containerized deployment as shown in the README)
• Access to a web browser automation driver (Playwright) as required by the project

Option A – Build from source and run locally (CLI/JAR):

1. Clone the repository
2. Build the project

mvn clean package -DskipTests

3. Run the CLI login tool (example)

java -cp target/app.jar -Dloader.main=com.lv.xhsmcp.login.LoginCli org.springframework.boot.loader.launch.PropertiesLauncher

Option B – Run via Docker (as described in the README):

1. Build the Docker image

docker buildx build -t java-xhs-mcp:latest .

2. Run the container (maps Playwright browsers and uses the image from the README)

docker run --rm -e PLAYWRIGHT_BROWSERS_PATH=/ms-playwright -v pw-browsers:/ms-playwright java-xhs-mcp:latest /bin/bash

3. Access the MCP endpoint at http://127.0.0.1:8081/mcp

Notes:

• The project relies on valid login cookies and, for posting content, a valid xsec_token.
• The Docker deployment follows the guidance in the README and uses a named volume for Playwright browsers.

Tips and common considerations:

• Ensure you have valid Xiaohongshu cookies for login and the necessary xsec_token for posting actions.
• When running via Docker, you may need to adjust the port mapping if you customize the server port; the README uses 8081 by default.
• The Playwright browsers path is mounted to /ms-playwright; make sure the volume pw-browsers is available on your host.
• For MCP integration, you can point your MCP client at http://localhost:8081/mcp as shown in the integration example in the README.
• This is MIT-licensed; review the LICENSE for terms and compliance.