# How to Set Up XiaoHongShu on Server Environments Using the xiaohongshu-mcp Docker Container

> Easily set up XiaoHongShu on your server using the xiaohongshu-mcp Docker container. Deploy, register the endpoint, and let Agent Reach handle command routing for seamless integration.

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

---

**Deploy the `xpzouying/xiaohongshu-mcp` Docker container on port 18060, register the endpoint with `mcporter config add xiaohongshu http://localhost:18060/mcp`, and Agent Reach automatically routes XiaoHongShu commands through the headless MCP server.**

The Agent-Reach repository supports XiaoHongShu (XHS) as a first-class channel with multiple backend options. When you need to set up XiaoHongShu on server environments using the xiaohongshu-mcp Docker container, you bypass the graphical Chrome dependency by deploying a self-contained headless browser that exposes a local HTTP service for the CLI to consume.

## Why Server Deployments Require the xiaohongshu-mcp Container

Agent Reach treats XiaoHongShu as a channel that can be powered by three distinct backends: **OpenCLI** (desktop), **xhs-cli** (legacy), and **xiaohongshu-mcp** (headless server). On machines without a graphical display, OpenCLI fails because it expects an interactive Chrome session. The `xiaohongshu-mcp` image solves this by bundling a headless browser and a lightweight HTTP service that listens on port 18060, allowing the Agent Reach CLI to communicate via the **mcporter** utility instead of native GUI automation.

## Prerequisites

Before deploying, ensure your server meets these requirements:

- **Docker** installed and running (for container orchestration)
- **Agent Reach CLI** installed (`agent-reach` command available)
- **mcporter** utility installed (handles MCP service registration)

## Step 1: Launch the xiaohongshu-mcp Docker Container

Pull and run the official image in detached mode, mapping port 18060 to the host. This container initializes the headless browser environment and starts the MCP HTTP service.

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

```

The container exposes `http://localhost:18060/mcp` as the MCP endpoint. No additional configuration is required inside the container itself.

## Step 2: Register the Service with mcporter

Agent Reach discovers the MCP backend through the `mcporter` configuration. Register the localhost endpoint so the channel knows where to route requests.

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

```

This command stores the endpoint mapping in `mcporter`'s local registry, enabling Agent Reach to query service health before attempting XHS operations.

## Step 3: Verify the Channel Status

Run the diagnostic command to confirm Agent Reach detects the MCP backend and reports the channel as operational.

```bash
agent-reach doctor

```

You should see output indicating **XiaoHongShu … ✅**, confirming that the `xiaohongshu-mcp` container is reachable and the `mcporter` registration is valid. If the service is running but unregistered, the CLI returns a *warn* status with the exact `mcporter config add` command needed.

## How Backend Selection Works in Agent Reach

The channel implementation in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) handles backend discovery through its `check()` method (lines 60-90). This method probes candidates in order—OpenCLI, xhs-cli, and finally xiaohongshu-mcp—and selects the first backend reporting *ok* or *warn* status.

The MCP-specific logic resides in `_check_mcp()` (lines 14-33). This function first verifies that the HTTP endpoint `http://localhost:18060/mcp` is reachable, then queries `mcporter` to confirm whether the XHS service has been registered (lines 14-21). If the container is running but `mcporter` lacks the configuration, the channel returns a *warn* state with remediation instructions.

## Executing XiaoHongShu Commands

Once configured, all XHS interactions route through the MCP server transparently. The implementation in [`agent_reach/integrations/mcp_server.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/integrations/mcp_server.py) handles the wire protocol between the CLI and the Docker container.

Example commands that now work on your headless server:

```bash

# Search for travel tips

agent-reach read xiaohongshu "search" "travel tips" -f yaml

# Retrieve specific note details

agent-reach read xiaohongshu "note" "NOTE_ID_HERE"

# Fetch comments on a note

agent-reach read xiaohongshu "comments" "NOTE_ID_HERE"

```

## Troubleshooting Common Issues

**Port Conflicts:** If port 18060 is already in use, map the container to an alternative port (e.g., `-p 18061:18060`), but remember to update the `mcporter` registration URL accordingly.

**Registration Failures:** If `agent-reach doctor` shows a warning despite the container running, verify that `mcporter config add xiaohongshu http://localhost:18060/mcp` executed successfully and that the URL matches your port mapping.

**Container Health:** Check Docker logs for the xiaohongshu-mcp process if the HTTP endpoint is unreachable: `docker logs xiaohongshu-mcp`.

## Summary

- The **xiaohongshu-mcp** Docker container provides a headless browser environment for XiaoHongShu automation on servers without GUI capabilities.
- **mcporter** registration (`mcporter config add xiaohongshu http://localhost:18060/mcp`) is mandatory for Agent Reach to discover the service.
- The channel logic in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) automatically prefers the MCP backend when graphical options are unavailable.
- Once running, standard `agent-reach read xiaohongshu` commands execute transparently through the containerized MCP server.

## Frequently Asked Questions

### What is the difference between xiaohongshu-mcp and xhs-cli?

**xiaohongshu-mcp** is a Dockerized headless browser service designed for server environments, while **xhs-cli** is a legacy command-line tool that typically requires desktop dependencies. The MCP version exposes an HTTP interface that Agent Reach queries via `mcporter`, whereas xhs-cli runs as a direct subprocess. On headless servers, only the MCP variant provides reliable automation without display servers or graphical Chrome installations.

### Can I run the xiaohongshu-mcp container on a different port?

Yes, modify the Docker port mapping (e.g., `-p 18061:18060`) and update the corresponding `mcporter` registration URL to match. The container internally always listens on port 18060, but the host-side port is configurable. Ensure the `mcporter config add` command reflects the host port you selected.

### How does Agent Reach detect if the MCP service is running?

According to the source code in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py), the `_check_mcp()` method performs two checks: it sends an HTTP request to `http://localhost:18060/mcp` to verify network reachability (lines 22-33), then interrogates `mcporter` to confirm the service is registered in its local configuration (lines 14-21). Both conditions must be satisfied for the channel to report healthy status.

### Is the xiaohongshu-mcp container suitable for production use?

The container is designed for stable, headless server operation as documented in [`agent_reach/guides/setup-xiaohongshu.md`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/guides/setup-xiaohongshu.md) (lines 72-84). For production deployments, ensure you implement Docker restart policies (e.g., `--restart unless-stopped`), monitor the container logs, and secure the port 18060 binding to localhost only (or behind a firewall) to prevent unauthorized MCP access.