How to Set Up XiaoHongshu on Desktop vs Server for Agent-Reach

Agent-Reach automatically selects the optimal XiaoHongshu backend—OpenCLI for desktop environments that reuse your Chrome session, or xiaohongshu-mcp for headless servers running a Dockerized Chromium instance—based on environment detection heuristics in _detect_environment().

Agent-Reach provides adaptive XiaoHongshu (XHS) integration that automatically configures the appropriate backend for your environment, whether you are running on a local workstation or a headless server. The framework intelligently probes system signals to determine which driver to activate, switching between three possible implementations defined in agent_reach/channels/xiaohongshu.py. This guide covers the complete configuration process for both scenarios using the actual implementation in the Panniantong/Agent-Reach repository.

How Agent-Reach Detects Desktop vs Server Environments

The detection logic resides in _detect_environment() inside agent_reach/cli.py (lines 555-595). This function examines environment variables, filesystem markers, and systemd-detect-virt to classify the host as "local" or "server".

Typical server signals include:

• SSH_CONNECTION or SSH_CLIENT environment variables
• Presence of /.dockerenv or /run/.containerenv
• Absence of DISPLAY or WAYLAND_DISPLAY
• Cloud-VM identifiers in /sys/...

If at least two of these clues appear, the CLI treats the host as a server.

The channel selection happens in XiaoHongShuChannel.check() in agent_reach/channels/xiaohongshu.py (lines 60-90), which probes three backends in order: OpenCLI, xiaohongshu-mcp, then xhs-cli, picking the first that reports "ok".

Desktop Setup: Using OpenCLI for Local Workstations

For desktop or local workstations with a visible display, Agent-Reach uses the OpenCLI backend to reuse your existing Chrome session. This requires no additional virtualization or containerization.

Installation Steps

Run the installer with the XHS channel:

agent-reach install --env=local --channels=xiaohongshu

This triggers _install_xhs_deps() → _install_opencli_deps() (see agent_reach/cli.py lines 302-332).

Ensure Node.js is present, then the script runs npm install -g opencli. After installation, the CLI prints the Chrome extension URL (OPENCLI_EXTENSION_URL). Open that URL in Chrome, click Add to Chrome, then verify the handshake:

opencli doctor

Import cookies if you need access to private notes or authenticated content:

agent-reach configure xhs-cookies '<cookie header>'

The helper _configure_xhs_cookies() (see agent_reach/cli.py lines 552-618) parses the header or a Cookie-Editor JSON export and stores it for the OpenCLI backend.

Validate the configuration:

agent-reach doctor

You should see a line like "OpenCLI 可用（复用浏览器登录态）" under the XiaoHongshu section.

Server Setup: Deploying xiaohongshu-mcp for Headless Environments

For servers, SSH sessions, Docker containers, or cloud VMs without a display, Agent-Reach uses the xiaohongshu-mcp service. This backend starts a self-contained headless Chromium instance that the agent communicates with over HTTP.

Installation Steps

Run the installer with the server flag:

agent-reach install --env=server --channels=xiaohongshu

Since --env=server forces the server path, _install_xhs_deps() skips OpenCLI and prints a guide for the MCP service (see agent_reach/cli.py lines 315-324).

Download the MCP binary:

mkdir -p ~/.agent-reach/tools/
cd ~/.agent-reach/tools/
curl -L -o xiaohongshu-mcp.tar.gz https://github.com/xpzouying/xiaohongshu-mcp/releases/latest/download/xiaohongshu-mcp-linux-amd64.tar.gz
tar xzf xiaohongshu-mcp.tar.gz
chmod +x xiaohongshu-mcp

Start the Docker container:

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

The service downloads a ~150 MiB headless Chromium on first start.

Connect Agent-Reach to the service using mcporter (installed automatically by _install_mcporter() in agent_reach/cli.py):

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

Authenticate via QR code—the first request to the MCP service prints a QR code URL in its logs. Scan it with the XHS app to store authenticated cookies.

Optionally inject cookies manually if you have a Cookie-Editor export:

agent-reach configure xhs-cookies '[{"name":"xhsid","value":"…","domain":".xiaohongshu.com"}]'

The helper detects Docker, copies the JSON into the running container, and places it at the path expected by the MCP service.

Validate the setup:

agent-reach doctor

The XiaoHongshu section should display "xiaohongshu-mcp 服务运行中" with a hint that mcporter can call xiaohongshu.search_feeds(...).

Fallback: Legacy xhs-cli

If neither OpenCLI nor xiaohongshu-mcp is available, the system falls back to the legacy xhs CLI. The _check_xhs_cli() method in xiaohongshu.py checks for this binary. While functional on both desktop and server, it requires manual xhs login configuration and lacks the zero-config benefits of OpenCLI or the headless capabilities of MCP. Note that upstream maintenance stopped in 2026.

Summary

• Environment Detection: The _detect_environment() function in agent_reach/cli.py automatically classifies hosts as "local" or "server" based on SSH variables, Docker markers, and display availability.
• Desktop Workflow: Uses OpenCLI to reuse existing Chrome sessions via npm install -g opencli and a browser extension, configured through _install_opencli_deps().
• Server Workflow: Deploys the xiaohongshu-mcp Docker container on port 18060, managed via mcporter to provide headless Chromium automation.
• Cookie Management: Both backends support cookie injection via agent-reach configure xhs-cookies, with automatic Docker container detection for server deployments.
• Validation: Use agent-reach doctor to verify backend status, checking for "OpenCLI 可用" (desktop) or "xiaohongshu-mcp 服务运行中" (server).

Frequently Asked Questions

How does Agent-Reach determine whether to use OpenCLI or xiaohongshu-mcp?

The framework probes three backends in sequence within XiaoHongShuChannel.check() in agent_reach/channels/xiaohongshu.py (lines 60-90). It first attempts OpenCLI, which requires a visible display and the Chrome extension. If that fails, it checks for the xiaohongshu-mcp HTTP service on localhost:18060. The environment classification is performed by _detect_environment() in agent_reach/cli.py, which looks for server indicators like SSH_CONNECTION, /.dockerenv, or missing DISPLAY variables.

Can I manually force a specific backend instead of auto-detection?

Yes. Pass the --env=local flag to force the OpenCLI desktop path, or --env=server to skip OpenCLI and configure for MCP. These flags directly influence the _install_xhs_deps() logic in agent_reach/cli.py, bypassing the automatic environment detection heuristics.

What if the xiaohongshu-mcp Docker container fails to start on my server?

Ensure Docker is installed and port 18060 is not already in use. The container downloads a ~150 MiB headless Chromium on first start, so verify you have sufficient disk space and internet connectivity. If issues persist, you can inject cookies manually using agent-reach configure xhs-cookies with a Cookie-Editor JSON export, which the helper will copy into the container if it detects a running Docker instance.

Is the legacy xhs-cli backend still maintained for Agent-Reach?

No. According to the source code comments in xiaohongshu.py, the upstream xhs CLI stopped updating in 2026, and it is retained only as a fallback. The xhs-cli backend is checked last in XiaoHongShuChannel.check() and should only be used if OpenCLI and xiaohongshu-mcp are unavailable. New deployments should use OpenCLI for desktops or xiaohongshu-mcp for servers.

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