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

> Easily configure XiaoHongShu cookies for xiaohongshu-mcp using the CLI. Import browser cookies for authenticated API access without local browser automation. Learn how now.

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

---

**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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/docs/cookie-export.md) details the recommended 30-second export method.

### Import Cookies Using the CLI

Run the configuration command from your terminal:

```bash
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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:

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

```

### Verify the Connection

Confirm the backend is active and authenticated:

```bash
agent-reach doctor | grep xiaohongshu

```

The `XiaoHongShuChannel` class in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main//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`](https://github.com/Panniantong/Agent-Reach/blob/main/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):**

```bash

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

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

```

**Import from JSON array:**

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

```

**Check configuration status:**

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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.