How to Set Up XiaoHongShu with xiaohongshu-mcp on Server Environments

To set up XiaoHongShu with xiaohongshu-mcp on server environments, download the pre-built binary, run the container on port 18060, register the endpoint with mcporter config add xiaohongshu http://localhost:18060/mcp, and verify connectivity using agent-reach doctor.

Agent-Reach supports XiaoHongShu (小红书) integration through three possible backends: OpenCLI, xiaohongshu-mcp, and the legacy xhs-cli. On headless servers, OpenCLI is incompatible because it requires a local Chrome session, making the self-contained xiaohongshu-mcp service the only viable option. This guide provides the exact steps to configure the MCP (Model Context Protocol) service according to the Panniantong/Agent-Reach source code.

Why xiaohongshu-mcp is Required for Headless Servers

OpenCLI depends on a local browser installation that cannot initialize in headless server environments without a display server. The xiaohongshu-mcp binary solves this by shipping with a lightweight, headless Chromium instance that authenticates via QR code without external browser dependencies. According to the probe logic in agent_reach/channels/xiaohongshu.py (lines 22-38), Agent-Reach validates the _MCP_ENDPOINT at http://localhost:18060/mcp to determine if the backend is alive using the _mcp_service_reachable check.

Prerequisites

• Docker installed (recommended) or ability to run Linux binaries
• Port 18060 available on the host
• mcporter CLI tool installed (bundled with Agent-Reach)
• Network access to download ~150 MiB Chromium binaries on first run

Step-by-Step Installation

1. Download the xiaohongshu-mcp Binary

Download the pre-built executable from the official GitHub releases to a consistent location:

mkdir -p ~/.agent-reach/tools && cd ~/.agent-reach/tools
curl -L -o xiaohongshu-mcp https://github.com/xpzouying/xiaohongshu-mcp/releases/download/vX.Y.Z/xiaohongshu-mcp-linux-amd64
chmod +x xiaohongshu-mcp

The binary contains the headless Chromium runtime required for authentication and scraping.

2. Start the Container Service

The simplest method uses Docker to expose the service on port 18060:

docker run -d --name xiaohongshu-mcp -p 18060:18060 xpzouying/xiaohongshu-mcp

Wait for the container to report "ready" after downloading the initial Chromium binaries (~150 MiB).

Alternatively, run the binary directly:

./xiaohongshu-mcp --port 18060 &

3. Authenticate via QR Code

Once the service is running, open a browser on any machine and navigate to:

http://<server-ip>:18060/mcp

Scan the displayed QR code with the XiaoHongShu mobile app. The service stores the resulting session cookies inside the container at $COOKIES_PATH (default /app/data/cookies.json), persisting authentication across restarts.

4. Register with mcporter

Register the service endpoint so Agent-Reach can route RPC calls to it:

mcporter config add xiaohongshu http://localhost:18060/mcp

This configuration enables the _check_mcp method in agent_reach/channels/xiaohongshu.py (lines 13-30) to detect the backend and execute commands via mcporter call "xiaohongshu.search_feeds(...)".

5. Verify the Setup

Run the diagnostic command to confirm the integration:

agent-reach doctor

Expected output includes:

xiaohongshu-mcp 服务运行中（mcporter call 'xiaohongshu.search_feeds(keyword: "...")'）。

If the service is running but unregistered, the CLI helper _install_xhs_deps in agent_reach/cli.py (lines 25-44) prints the specific configuration command needed to complete the setup.

Technical Implementation Details

Agent-Reach communicates with xiaohongshu-mcp through a structured probe mechanism. The XiaoHongShuChannel class in agent_reach/channels/xiaohongshu.py implements:

• _mcp_service_reachable: Verifies the HTTP endpoint at http://localhost:18060/mcp is responsive (lines 22-38)
• _check_mcp: Validates that mcporter can communicate with the registered service and lists available methods (lines 13-30)
• format_xhs_result: Strips unnecessary fields from search responses before LLM processing (lines 40-59)

The generic probing utility in agent_reach/probe.py handles the underlying command execution checks, while agent_reach/config.py stores the xiaohongshu_backend selection and mcporter configuration paths.

Code Examples

Checking Service Status Programmatically

from agent_reach.channels.xiaohongshu import XiaoHongShuChannel

ch = XiaoHongShuChannel()
status, msg = ch.check()
print(status)   # → "ok" if MCP is reachable and mcporter is configured

print(msg)      # Human-readable hint about configuration status

Executing Search Queries

Search XiaoHongShu feeds directly via the MCP interface:

mcporter call "xiaohongshu.search_feeds(keyword: \"AI agents\")"

The JSON response can be processed through format_xhs_result to extract relevant fields for downstream LLM consumption.

Summary

• OpenCLI is incompatible with headless server environments; use xiaohongshu-mcp instead.
• Install the binary or Docker container and expose it on port 18060.
• Authenticate via QR code at http://<server-ip>:18060/mcp to persist cookies.
• Register the endpoint using mcporter config add xiaohongshu http://localhost:18060/mcp.
• Verify the integration with agent-reach doctor, which references the implementation in agent_reach/cli.py and agent_reach/channels/xiaohongshu.py.
• Use mcporter call to execute searches programmatically without browser interaction.

Frequently Asked Questions

Can I use OpenCLI on a server instead of xiaohongshu-mcp?

No. OpenCLI requires a local Chrome browser session with a display server, which is unavailable in typical headless server environments. The xiaohongshu-mcp binary embeds a headless Chromium instance specifically designed for server deployments.

Where are authentication cookies stored?

The xiaohongshu-mcp service stores session cookies at /app/data/cookies.json inside the container (configurable via $COOKIES_PATH). These cookies persist across container restarts, maintaining your login state without requiring repeated QR code scans.

How do I troubleshoot if agent-reach doctor reports the service as unreachable?

First, verify the container is running and port 18060 is accessible. Check that you registered the service with mcporter config add xiaohongshu http://localhost:18060/mcp. The diagnostic logic in agent_reach/channels/xiaohongshu.py specifically checks for the _MCP_ENDPOINT registration; if missing, the _check_mcp method will return a configuration warning indicating the service is running but not registered.

Is the xiaohongshu-mcp service compatible with ARM architectures?

The official releases typically provide AMD64 binaries. For ARM servers (like AWS Graviton or Raspberry Pi), you must build the container from source or use an emulator, as the pre-built Docker image at xpzouying/xiaohongshu-mcp may not include ARM variants. Check the GitHub releases page for architecture-specific assets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}