Setting up XiaoHongShu (Xiaohongshu) with Cookie-Editor Export: Complete Guide

Export your XiaoHongShu cookies using the Cookie-Editor browser extension and copy them into the xiaohongshu-mcp Docker container at /app/data/cookies.json to authenticate Agent Reach's channel.

Agent Reach treats XiaoHongShu as a multi-backend channel designed for both desktop automation and headless server deployments. Setting up XiaoHongShu (Xiaohongshu) with Cookie-Editor export is the recommended method for server environments where browser automation requires imported session data. This guide references the actual implementation in Panniantong/Agent-Reach to ensure precise configuration.

Understanding the XiaoHongShu Channel Architecture

The channel implementation resides in agent_reach/channels/xiaohongshu.py and supports three distinct backends ordered by preference.

The Three Backend Options

Backend	Mechanism	Selection Criteria
OpenCLI	Reuses a locally logged-in Chrome instance via the generic OpenCLI wrapper	Desktop machines with existing Chrome profiles containing valid XiaoHongShu sessions
xiaohongshu-mcp	Self-contained headless-browser Docker service storing cookies in /app/data/cookies.json	Servers without Chrome; service reachable at http://localhost:18060/mcp
xhs-cli	Legacy CLI tool that directly communicates with the XiaoHongShu API	Fallback for older installations (functional but unmaintained)

How the Channel Discovers Available Backends

The check() method (lines 61-90 in agent_reach/channels/xiaohongshu.py) iterates through the backend priority list, probing each with dedicated helpers:

• OpenCLI → opencli_status() (defined in agent_reach/backends/opencli.py)
• xiaohongshu-mcp → _mcp_service_reachable() verifies the HTTP endpoint (lines 22-38) and checks mcporter config for a xiaohongshu entry
• xhs-cli → probe_command("xhs", ["status"], …) validates binary health (lines 31-58)

The first backend returning "ok" becomes self.active_backend. If none fully function, the best-available candidate triggers a warning to guide remediation.

Formatting API Responses for LLM Consumption

Raw XiaoHongShu API payloads contain redundant fields that increase token usage. The format_xhs_result() function (lines 40-58) normalizes any payload:

from agent_reach.channels.xiaohongshu import format_xhs_result

clean = format_xhs_result(raw_api_data)

• List payloads: Each element passes through _clean_note() (lines 62-129)
• Single objects: Extracts inner items lists or the note directly

Data Extracted by _clean_note()

The cleaning routine (lines 62-129) preserves only LLM-relevant fields:

• Core metadata: id, note_id, title, desc, type, time (lines 73-75)
• Content: content fallback when desc is missing (lines 78-80)
• Author info: nickname, user_id (lines 82-86)
• Engagement: liked_count, collected_count (lines 89-98)
• Media: Image URLs (lines 100-108)
• Tags: Tag names (lines 114-123)
• Comments: Processed via _clean_comment() (lines 33-46), keeping only text, author nickname, like_count, and sub_comment_count

This extraction occurs automatically when using the channel through AgentReach.search().

Setting up XiaoHongShu (Xiaohongshu) with Cookie-Editor Export

XiaoHongShu authentication relies on cookie-based sessions. For the xiaohongshu-mcp backend, import cookies using the Cookie-Editor extension:

1. Export cookies from your browser using Cookie-Editor (select "Copy as JSON")
2. Prepare the JSON array format: [{"name":"xhsid","value":"…","domain":".xiaohongshu.com","path":"…"}, …]
3. Deploy the Docker container and import the cookies:

# Start the container

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

# Create the cookie file locally

cat > /tmp/xhs_cookies.json <<'EOF'
[{"name":"xhsid","value":"your_session_value","domain":".xiaohongshu.com","path":"/"}]
EOF

# Copy into the container's expected location

docker cp /tmp/xhs_cookies.json xiaohongshu-mcp:/app/data/cookies.json

If the container runs prior to configuration, agent_reach/cli.py (lines 707-720) automatically suggests these steps when executing install --env=auto. Once cookies reside at /app/data/cookies.json, the service authenticates silently and Agent Reach operates without further interaction.

Integrating the Channel Into Your Workflow

Access the configured channel through the main Agent Reach interface:

from agent_reach.core import AgentReach

# Initialize from ~/.agent_reach.yml or environment variables

ar = AgentReach()

# Search automatically routes to the active backend

results = ar.search("xiaohongshu", "artificial intelligence")

# Results are pre-formatted by format_xhs_result()

print(results[0]["title"])
print(results[0]["images"])

The can_handle() method (lines 55-58) routes any URL containing xiaohongshu.com or xhslink.com to this channel.

Troubleshooting Common Setup Issues

Symptom	Root Cause	Solution
check() warns: "xiaohongshu-mcp 服务在跑但 mcporter 未接入"	Container running but mcporter lacks configuration	Execute mcporter config add xiaohongshu http://localhost:18060/mcp (see lines 226-229)
xhs-cli returns "not_authenticated"	Missing cookies in container	Export fresh cookies via Cookie-Editor and copy to /app/data/cookies.json
OpenCLI reports "broken" on servers	No Chrome/desktop environment available	Switch to xiaohongshu-mcp backend by installing the Docker image

Summary

• Agent Reach implements XiaoHongShu support through three backends in agent_reach/channels/xiaohongshu.py, preferring xiaohongshu-mcp for server deployments
• Authentication requires copying Cookie-Editor exports into the Docker container at /app/data/cookies.json
• Data optimization occurs automatically via format_xhs_result() and _clean_note(), stripping redundant API fields to reduce LLM token usage
• Backend selection happens dynamically through the check() method (lines 61-90), probing OpenCLI, MCP, and CLI options sequentially

Frequently Asked Questions

How do I export cookies from Cookie-Editor for XiaoHongShu?

Install the Cookie-Editor browser extension, navigate to xiaohongshu.com while logged in, open the extension, and click "Copy as JSON." This produces an array of cookie objects that you save to /tmp/xhs_cookies.json and copy into the running Docker container at /app/data/cookies.json.

What is the difference between the three backends?

OpenCLI requires a local Chrome installation with an existing user profile; xiaohongshu-mcp runs as a headless Docker service accepting imported cookies; xhs-cli is a legacy Python CLI that directly hits the API but receives no maintenance updates. The check() method prioritizes them in that order.

Where does the xiaohongshu-mcp service store cookies?

The service expects cookies at /app/data/cookies.json inside the container. When you run docker cp /tmp/xhs_cookies.json xiaohongshu-mcp:/app/data/cookies.json, you place the session data where the headless browser can access it for authentication.

Why is my OpenCLI backend failing on a server?

OpenCLI depends on a graphical Chrome instance and existing user profiles. Servers typically lack these dependencies, causing the probe to fail. Deploy the xpzouying/xiaohongshu-mcp Docker image instead and authenticate via Cookie-Editor export for server environments.

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