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

> Easily set up XiaoHongShu with xiaohongshu-mcp on your server. Follow simple steps to download, run, register the endpoint, and verify connectivity for seamless integration.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-07-13

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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:

```bash
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:

```bash
./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`](https://github.com/Panniantong/Agent-Reach/blob/main//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:

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

```

This configuration enables the `_check_mcp` method in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/probe.py) handles the underlying command execution checks, while [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) stores the `xiaohongshu_backend` selection and mcporter configuration paths.

## Code Examples

### Checking Service Status Programmatically

```python
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:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main//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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.