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

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.

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.

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.

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 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 handles the wire protocol between the CLI and the Docker container.

Example commands that now work on your headless server:

# 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 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, 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 (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.

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