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

Agent Reach automatically selects between OpenCLI for desktop environments and xiaohongshu-mcp for server environments, probing three backend candidates in order and falling back to the legacy xhs-cli if needed.

Agent Reach provides adaptive XiaoHongShu (Xiaohongshu or XHS) integration that configures the appropriate backend for your specific environment. Whether you are developing on a local workstation with a GUI or deploying to a headless cloud server, the framework handles authentication and session management through environment-specific adapters implemented in the Panniantong/Agent-Reach repository.

How Agent Reach Detects Server vs Desktop Environments

Agent Reach determines your host type through the _detect_environment() helper in agent_reach/cli.py (lines 555–595). This function examines environment variables, filesystem markers, and virtualization indicators to return either "server" or "local".

The probe checks for server signals including:

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

If at least two of these signals appear, the CLI treats the host as a server. This detection drives the selection logic in XiaoHongShuChannel.check() within agent_reach/channels/xiaohongshu.py (lines 60–90), which probes three backend candidates sequentially and selects the first reporting "ok".

Desktop Setup: OpenCLI Backend

For local workstations with a visible display, Agent Reach uses the OpenCLI backend to reuse your existing Chrome browser session.

Installation

Run the installer with the XHS channel specified:

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

This command invokes _install_xhs_deps() → _install_opencli_deps() (see agent_reach/cli.py, lines 302–332). The process requires Node.js and automatically runs npm install -g opencli.

Chrome Extension Configuration

After npm installation completes, the CLI prints the OPENCLI_EXTENSION_URL. Complete the setup by:

1. Opening the URL in Chrome and clicking Add to Chrome
2. Running the verification command:

opencli doctor

This confirms the Chrome-extension handshake is functioning.

Cookie Import (Optional)

To import existing XHS credentials for private notes or authenticated actions:

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

The helper _configure_xhs_cookies() (defined in agent_reach/cli.py, lines 552–618) parses either a raw header string or a Cookie-Editor JSON export and stores it for the OpenCLI backend.

Validation

Verify the desktop configuration:

agent-reach doctor

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

Server Setup: xiaohongshu-mcp Backend

For headless servers, SSH sessions, or Docker containers, Agent Reach uses the xiaohongshu-mcp service running a headless Chromium instance.

Installation

Force the server installation path:

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

Since --env=server forces the server path, _install_xhs_deps() skips OpenCLI and prepares the MCP service configuration (see agent_reach/cli.py, lines 315–324).

MCP Service Deployment

Download and run 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 container (the binary handles this internally, or run Docker directly):

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

The service downloads a ~150 MiB headless Chromium on first startup and exposes an HTTP endpoint at http://localhost:18060/mcp.

Connect Agent Reach to the Service

Configure the MCP endpoint using mcporter (installed automatically by the installer, see _install_mcporter() in agent_reach/cli.py):

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

Authentication

The first request to the MCP service prints a QR code URL in its logs. Scan this code with the XHS mobile app to authenticate. The service stores authenticated cookies automatically for subsequent requests.

Manual Cookie Injection (Optional)

If you have an existing Cookie-Editor export, inject it directly:

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

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

Validation

Run the health check:

agent-reach doctor

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

Fallback: xhs-cli Backend

If neither OpenCLI nor MCP is available, the installer checks for the legacy xhs binary via _check_xhs_cli() in xiaohongshu.py. While this backend works on both desktop and server, it lacks the zero-config convenience of OpenCLI and the containerized isolation of MCP. Upstream maintenance ceased in 2026, so this remains strictly a backup option.

Summary

• Automatic detection via _detect_environment() examines SSH variables, Docker markers, and display availability to choose the appropriate backend.
• Desktop environments use OpenCLI to reuse existing Chrome sessions with minimal configuration.
• Server environments run the xiaohongshu-mcp Docker service on port 18060 for headless operation.
• Cookie management works across both environments through agent-reach configure xhs-cookies.
• Validation统一通过 agent-reach doctor 检查，显示特定后端状态。

Frequently Asked Questions

How does Agent Reach determine if I'm on a server versus a desktop?

The framework runs _detect_environment() in agent_reach/cli.py (lines 555–595), which checks for server indicators like SSH_CONNECTION, /.dockerenv, and missing DISPLAY variables. If two or more signals are present, it classifies the host as a server and prioritizes the xiaohongshu-mcp backend over OpenCLI.

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

Yes. Use the --env flag explicitly: agent-reach install --env=local --channels=xiaohongshu forces the OpenCLI path, while --env=server forces the MCP container setup. This overrides the automatic probing logic in XiaoHongShuChannel.check().

What if the Chrome extension fails to connect on desktop?

Run opencli doctor to diagnose the handshake. Ensure you have installed the extension from the URL printed during agent-reach install, and verify that Chrome is running with the same user profile that installed the extension. Check agent_reach/backends/opencli.py for the opencli_status implementation if debugging programmatically.

How do I persist cookies on the server after the initial QR login?

The xiaohongshu-mcp service automatically persists authenticated sessions within its Docker container. If you need to migrate or backup cookies, use agent-reach configure xhs-cookies with a JSON export from Cookie-Editor; the helper detects the containerized environment and copies the credentials to the correct path inside the running MCP container.

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