# How to Configure XiaoHongShu (Xiaohongshu) with OpenCLI vs xiaohongshu-mcp on Servers

> Configure XiaoHongShu on servers using OpenCLI or xiaohongshu-mcp. Discover the differences in setup authentication and operational requirements for each method.

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

---

**OpenCLI requires a graphical Chrome browser on desktops and reuses existing login cookies, while xiaohongshu-mcp runs a headless Chromium HTTP service on port 18060 for servers, requiring QR-code authentication via mcporter.**

The **XiaoHongShuChannel** class in the Panniantong/Agent-Reach repository supports three backends, but production deployments typically choose between **OpenCLI** for desktop workstations and **xiaohongshu-mcp** for headless servers. The channel implementation in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) automatically probes these backends during the `doctor` check, selecting the first available option based on a hardcoded priority list.

## Desktop Configuration with OpenCLI

OpenCLI is the default backend for graphical environments. It leverages an existing Chrome login session through a browser extension, eliminating the need for manual QR-code authentication.

### Install the OpenCLI Extension and Binary

The OpenCLI backend requires the Chrome extension and a local binary. Agent-Reach provides an automated installation command:

```bash

# Installs OpenCLI and registers the XiaoHongShu channel

agent-reach install --channels opencli

```

This command downloads the OpenCLI binary to your system path and verifies the Chrome extension is present. The installation script automatically detects your operating system and places the binary in the appropriate location.

### Verify OpenCLI Status

Run the diagnostic tool to confirm the backend is operational:

```bash
agent-reach doctor

```

The `XiaoHongShuChannel.check()` method (lines 61-90 in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py)) calls `opencli_status()` to verify the extension is installed and the binary is executable. A successful check reports `OpenCLI 可用（复用浏览器登录态）`, indicating it will reuse your browser's existing XiaoHongShu cookies.

### Execute Commands

Once verified, invoke XiaoHongShu operations directly:

```bash
opencli xiaohongshu search "旅行" -f yaml

```

The OpenCLI wrapper contacts the Chrome extension via native messaging, extracts the current session cookies, and executes the requested operation without additional authentication steps.

## Server Configuration with xiaohongshu-mcp

For headless servers or CI environments without a graphical browser, **xiaohongshu-mcp** provides a headless Chromium instance accessible via HTTP. This backend requires explicit service management and QR-code authentication.

### Download and Launch the MCP Service

Download the appropriate release binary from the official repository and extract it to the Agent-Reach tools directory:

```bash

# Create tools directory if missing

mkdir -p ~/.agent-reach/tools/

# Download and extract (Linux x86_64 example)

curl -L https://github.com/xpzouying/xiaohongshu-mcp/releases/download/v1.0.0/xiaohongshu-mcp-linux-x86_64.tar.gz \
  | tar -xz -C ~/.agent-reach/tools/

# Start the service (first run downloads ~150MB headless Chromium)

~/.agent-reach/tools/xiaohongshu-mcp &

```

The service binds to `http://localhost:18060/mcp` by default and launches a bundled Chromium instance optimized for server environments.

### Configure mcporter and Authenticate

Register the MCP endpoint with Agent-Reach's port configuration tool:

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

```

The first run requires authentication via QR code. The XiaoHongShuChannel calls `get_login_qrcode` to generate a code that you scan with the XiaoHongShu mobile app. The `check()` method in lines 115-130 verifies the service is reachable via `_mcp_service_reachable()` and confirms the `mcporter` configuration entry exists.

### Execute Commands with Extended Timeout

Server-side operations require longer timeouts due to headless browser initialization:

```bash

# Search with 120-second timeout for headless browser operations

agent-reach xiaohongshu search "美食" --timeout 120000

```

The `--timeout` flag must specify at least 120000 milliseconds (120 seconds) to accommodate network operations and page rendering in the headless Chromium instance.

## Backend Selection Logic in Agent-Reach

The `XiaoHongShuChannel` class maintains a strict priority list defined in the `backends` attribute (lines 52-56 of [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py)):

1. **OpenCLI** - Tried first; checks for Chrome extension and binary
2. **xiaohongshu-mcp** - Fallback for headless environments; validates HTTP endpoint and mcporter config
3. **xhs-cli** - Legacy fallback (no longer recommended)

During `agent-reach doctor`, the `check()` implementation probes each candidate in sequence. The first backend returning `"ok"` becomes `self.active_backend` (lines 84-86) and handles all subsequent `read` and `search` operations.

## Key Differences Between OpenCLI and xiaohongshu-mcp

| Aspect | OpenCLI (Desktop) | xiaohongshu-mcp (Server) |
|--------|-------------------|---------------------------|
| **Installation** | Chrome extension + OpenCLI binary (`agent-reach install --channels opencli`) | Download MCP binary to `~/.agent-reach/tools/`, start service, configure `mcporter` |
| **Authentication** | Reuses existing Chrome cookies automatically | Requires QR-code scan on first run |
| **Dependencies** | Graphical Chrome browser required | Headless Chromium bundled; no GUI needed |
| **Performance** | Near-instant (local extension calls) | HTTP round-trip + browser rendering overhead |
| **Recommended for** | Local workstations with browsers | Cloud VPS, Docker containers, CI/CD pipelines |

## Code Examples

**OpenCLI (Desktop):**

```python
import subprocess

# Reuses Chrome login session

result = subprocess.run(
    ["opencli", "xiaohongshu", "search", "旅行", "-f", "yaml"],
    capture_output=True,
    text=True
)
print(result.stdout)

```

**xiaohongshu-mcp (Server):**

```python
import requests
import json

# Direct MCP HTTP API call

response = requests.post(
    "http://localhost:18060/mcp",
    json={
        "method": "xiaohongshu.search_feeds",
        "params": {"keyword": "旅行"}
    }
)

print(json.dumps(response.json(), ensure_ascii=False, indent=2))

```

## Summary

- **OpenCLI** is prioritized for desktop environments with Chrome, offering cookie reuse and faster execution through the `opencli` binary.
- **xiaohongshu-mcp** provides server-side capability via a headless Chromium service on port 18060, managed through `mcporter` configuration and requiring QR-code authentication.
- The `XiaoHongShuChannel` in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) automatically selects the first available backend during `agent-reach doctor` checks, defaulting to OpenCLI when present.
- Server deployments must specify `--timeout 120000` or higher to accommodate headless browser initialization times.

## Frequently Asked Questions

### Can I use OpenCLI on a headless server without a GUI?

No. OpenCLI requires a graphical Chrome browser and the OpenCLI extension to function. For headless servers, you must use **xiaohongshu-mcp**, which bundles its own headless Chromium instance and does not require a display server.

### Where does Agent-Reach store the MCP binary?

The standard installation path is `~/.agent-reach/tools/xiaohongshu-mcp`. The `check()` method in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) looks for the service at this location and verifies connectivity to `http://localhost:18060/mcp` before marking the backend as available.

### Why does the server setup require a longer timeout?

The xiaohongshu-mcp backend launches a headless Chromium browser for each session, which requires approximately 120 seconds to initialize, download assets, and execute JavaScript. The `--timeout 120000` flag (120,000 milliseconds) ensures the operation completes before Agent-Reach terminates the request.