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

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

# 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:

agent-reach doctor

The XiaoHongShuChannel.check() method (lines 61-90 in 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:

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:

# 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:

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:

# 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):

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):

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):

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 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 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.

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