How to Configure XiaoHongShu Cookies for xiaohongshu-mcp in Agent-Reach

Use the agent-reach configure xhs-cookies CLI command to import browser cookies into the running xiaohongshu-mcp container, enabling authenticated XiaoHongShu API access without local browser automation.

Agent-Reach supports three XiaoHongShu backends: OpenCLI, xiaohongshu-mcp (a headless-browser Docker container), and the legacy xhs-cli. When deploying the xiaohongshu-mcp service on a server, you must configure XiaoHongShu cookies to authenticate requests, as the container cannot access your local browser session directly.

Prerequisites

Before configuring cookies, ensure you have:

• Exported cookies from your local browser using Cookie-Editor or a similar extension (see the official guide in docs/cookie-export.md)
• The xiaohongshu-mcp Docker container running and accessible on port 18060
• The Agent-Reach CLI installed on the machine running the container

Step-by-Step Configuration Guide

Export Cookies from Your Browser

First, extract your XiaoHongShu session data from your browser. The recommended method uses the Cookie-Editor extension:

1. Navigate to xiaohongshu.com and log in
2. Open Cookie-Editor and export as Header String or JSON
3. Copy the exported value to your clipboard

The repository documentation at docs/cookie-export.md details the recommended 30-second export method.

Import Cookies Using the CLI

Run the configuration command from your terminal:

agent-reach configure xhs-cookies "web_session=abc123; another_cookie=def456"

This command invokes the internal helper _configure_xhs_cookies located in agent_reach/cli.py (lines 1175-1190). The helper automatically:

• Detects whether you provided a Cookie-Editor JSON array ([...]) or a header string (name=value; ...)
• Normalizes the data into a JSON array with required fields (name, value, domain, path)
• Copies the cookies into the running xiaohongshu-mcp container and restarts the service

Alternatively, pass the raw JSON array directly:

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

Verify the Connection

Confirm the backend is active and authenticated:

agent-reach doctor | grep xiaohongshu

The XiaoHongShuChannel class in agent_reach/channels/xiaohongshu.py (lines 22-34) probes the MCP service via the _mcp_service_reachable method, which checks http://localhost:18060/mcp. A successful configuration shows the service as "xiaohongshu-mcp" in the doctor output.

How Cookie Import Works Under the Hood

The _configure_xhs_cookies function in agent_reach/cli.py handles the configuration through three distinct paths:

Format Detection and Normalization

The helper inspects your input to determine if it is a JSON array (starting with [) or a semicolon-delimited header string. It converts header strings into the structured JSON format expected by the MCP container, ensuring fields like domain and path are properly parsed.

Docker Container Workflow

When Docker is available, the function:

• Verifies the xiaohongshu-mcp container is running (docker ps)
• Reads the container's COOKIES_PATH environment variable (defaulting to /app/cookies.json)
• Copies the normalized JSON file into the container using docker cp
• Restarts the container to reload the cookie file
• Calls mcporter call xiaohongshu.check_login_status() to verify authentication

Local File Fallback

If Docker is not installed, the helper writes the cookies to ~/.agent-reach/xhs-cookies.json with strict permissions (0o600). The make_private_dir utility in agent_reach/utils/paths.py creates the parent directory with 0o700 permissions to ensure only your user can access the sensitive data.

Complete Configuration Examples

Import from header string (most common):

# Export from Cookie-Editor as Header String, then paste:

agent-reach configure xhs-cookies "web_session=FR37HABC123; gid=xyz789.1234567890"

Import from JSON array:

agent-reach configure xhs-cookies "[{\"name\":\"web_session\",\"value\":\"FR37HABC123\",\"domain\":\".xiaohongshu.com\",\"path\":\"/\"}]"

Check configuration status:

# Should report xiaohongshu-mcp as active

agent-reach doctor

# Test specific functionality

mcporter call xiaohongshu.check_login_status()

Summary

• Export cookies from your browser using the Cookie-Editor extension or similar tool
• Import via CLI using agent-reach configure xhs-cookies '<data>', which handles both JSON and header-string formats
• The _configure_xhs_cookies helper in agent_reach/cli.py normalizes data and copies it into the xiaohongshu-mcp container
• Verify the configuration using agent-reach doctor to ensure the XiaoHongShuChannel detects the backend
• Without Docker, cookies are stored securely in ~/.agent-reach/xhs-cookies.json with 0o600 permissions

Frequently Asked Questions

What cookie format does xiaohongshu-mcp accept?

The xiaohongshu-mcp backend accepts either a JSON array (as exported by Cookie-Editor) or a plain header string (name1=value1; name2=value2). The _configure_xhs_cookies function in agent_reach/cli.py automatically detects the format and normalizes it into the JSON schema required by the container, which expects objects with name, value, domain, and path properties.

Where are cookies stored when Docker is not available?

If the Docker daemon is not running, the CLI writes the normalized cookie data to ~/.agent-reach/xhs-cookies.json on the local filesystem. The file is created with 0o600 permissions (read/write for owner only), and the parent directory is secured with 0o700 permissions via the make_private_dir utility in agent_reach/utils/paths.py.

How does the CLI verify the cookie configuration succeeded?

After copying cookies into the container, the _configure_xhs_cookies helper optionally verifies authentication by calling mcporter call xiaohongshu.check_login_status(). This validates that the imported cookies are valid and active. You can also run agent-reach doctor to see if the XiaoHongShuChannel class successfully probes the MCP service at http://localhost:18060/mcp.

Can I use the xiaohongshu-mcp backend without importing cookies?

No. The xiaohongshu-mcp backend requires valid session cookies to authenticate API requests to XiaoHongShu. Unlike the OpenCLI backend (which might support other authentication methods), the MCP container operates as a headless browser that relies on imported cookies to maintain session state. Without configuring cookies via agent-reach configure xhs-cookies, the service cannot authenticate requests.

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