How to Set Up XiaoHongShu (Xiaohongshu) on Server vs Desktop Environments with Agent Reach

Agent Reach automatically selects the optimal XiaoHongShu backend—OpenCLI for desktop environments with Chrome, xiaohongshu-mcp for headless servers, or xhs-cli as a fallback—based on environment detection logic in agent_reach/cli.py.

The Panniantong/Agent-Reach repository provides adaptive XiaoHongShu (Xiaohongshu) integration that automatically configures the appropriate backend for your specific environment. Whether you are running on a local workstation with a GUI or deploying to a headless cloud server, Agent Reach handles the complexity through intelligent environment detection. This guide explains how to set up XiaoHongShu (Xiaohongshu) on server vs desktop environments with Agent Reach using the three available backends.

How Agent Reach Detects Your Environment

The environment detection logic resides in the _detect_environment() helper function within agent_reach/cli.py (lines 555-595). This function examines system indicators to classify the host as either "server" or "local".

Agent Reach treats the host as a server when at least two of the following conditions are present:

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

When these signals indicate a desktop environment, the system prioritizes the OpenCLI backend; otherwise, it configures the xiaohongshu-mcp service.

Desktop Setup with OpenCLI

For desktop environments with a visible display, Agent Reach uses the OpenCLI backend to reuse your existing Chrome session. No Docker containers or separate browser instances are required.

1. Install the XiaoHongShu Channel

Run the installer with the local environment flag:

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

The installer executes _install_xhs_deps() which calls _install_opencli_deps() (lines 302-332 in agent_reach/cli.py) to set up the Node.js dependency and global npm package.

2. Install the Chrome Extension

After npm installation completes, the CLI displays the OPENCLI_EXTENSION_URL. Open this URL in Chrome, click Add to Chrome, then verify the extension handshake:

opencli doctor

3. Import Cookies (Optional)

If you need to import existing XHS cookies for private notes or authenticated access, use:

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

The _configure_xhs_cookies() function (lines 552-618 in agent_reach/cli.py) parses Cookie-Editor JSON exports or header strings and stores them for the OpenCLI backend.

4. Validate the Installation

Run the diagnostic command:

agent-reach doctor

Look for the status line indicating "OpenCLI 可用（复用浏览器登录态）" under the XiaoHongShu section.

Server Setup with xiaohongshu-mcp

For server or headless environments, Agent Reach deploys the xiaohongshu-mcp service in a Docker container. This backend runs a self-contained headless Chromium instance that the agent controls over HTTP.

1. Install with Server Flag

Force the server configuration path:

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

The _install_xhs_deps() function skips OpenCLI and provides MCP setup guidance (lines 315-324).

2. Download and Run the MCP Service

Create the tools directory and download the 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

Alternatively, run the Docker container directly:

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

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

3. Configure Agent Reach to Connect

Register the MCP endpoint with the mcporter tool (installed automatically by _install_mcporter()):

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

4. Authenticate via QR Code

The first request to the MCP service prints a QR code URL in its logs. Scan this code with the XiaoHongShu mobile app to establish an authenticated session. The service stores the resulting cookies automatically.

5. Inject Cookies Manually (Optional)

For existing Cookie-Editor exports or manual cookie strings:

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

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

6. Validate Server Setup

Confirm the service is running:

agent-reach doctor

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

Fallback to Legacy xhs-cli

If neither OpenCLI nor MCP is available, XiaoHongShuChannel.check() in agent_reach/channels/xiaohongshu.py (lines 60-90) probes for the legacy xhs binary via _check_xhs_cli(). While functional on both desktop and server, this backend is no longer maintained (upstream updates ceased in 2026) and lacks the zero-config convenience of OpenCLI or the headless capabilities of MCP.

Summary

• Desktop environments: Use OpenCLI to reuse Chrome sessions; install with --env=local and add the Chrome extension.
• Server environments: Use xiaohongshu-mcp in Docker; install with --env=server and configure mcporter to connect to localhost:18060.
• Environment detection: Automatic via _detect_environment() in agent_reach/cli.py using SSH vars, container markers, and display checks.
• Cookie management: Use agent-reach configure xhs-cookies for both backends; the CLI handles path translation for Docker containers.
• Validation: Always run agent-reach doctor to verify backend status and connectivity.

Frequently Asked Questions

How does Agent Reach decide which XiaoHongShu backend to use?

The XiaoHongShuChannel.check() method in agent_reach/channels/xiaohongshu.py probes three candidates in order: OpenCLI, xiaohongshu-mcp, and xhs-cli. It selects the first reporting "ok" status, with priority given to OpenCLI on desktops and MCP on servers based on _detect_environment() results.

Can I run the XiaoHongShu integration on a cloud VM without a GUI?

Yes. Deploy the xiaohongshu-mcp backend using Docker on your headless server. The service runs on port 18060 and provides a headless Chromium instance that Agent Reach controls via HTTP, eliminating the need for a display or Chrome installation.

What should I do if OpenCLI fails to connect on my desktop?

Run opencli doctor to verify the Chrome extension handshake. Ensure you installed the extension from the URL printed during agent-reach install. If issues persist, import cookies using agent-reach configure xhs-cookies or switch to the xiaohongshu-mcp backend by running the installer with --env=server.

Is the legacy xhs-cli backend still supported?

The xhs-cli backend remains as a fallback but is no longer maintained. The upstream project stopped updating in 2026. For production use, prefer OpenCLI for desktops or xiaohongshu-mcp for servers.

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