# How to Access Xiaohongshu Data Using Agent Reach: Three Backend Methods Explained

> Learn how to access Xiaohongshu data with Agent Reach. Discover three backend methods for efficient data extraction and analysis. Explore the Panniantong/Agent-Reach repository for details.

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

---

**Agent Reach provides access to Xiaohongshu data by orchestrating three upstream backends—OpenCLI, xiaohongshu-mcp, and xhs-cli—automatically selecting the first available option based on your environment.**

The Panniantong/Agent-Reach repository does not implement its own Xiaohongshu API client. Instead, it functions as an orchestration layer that detects your environment and invokes the appropriate upstream tool to interact with Xiaohongshu’s private API, handling authentication and data retrieval through existing authenticated sessions.

## Understanding the Backend Architecture

Agent Reach employs a **doctor** routine that probes three possible backends in sequential order. The probing logic resides in `XiaoHongShuChannel.check` within [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 60-96). The first fully usable backend is marked as *active* and used for all subsequent data requests.

### OpenCLI for Desktop Environments

The **OpenCLI** backend is selected when Agent Reach detects a desktop or laptop environment with an active Chrome session. This method reuses authenticated Chrome cookies from your browser, eliminating the need for separate API credentials. The command `opencli xiaohongshu …` communicates with the OpenCLI service, which forwards requests to Xiaohongshu’s private API.

### xiaohongshu-mcp for Server Environments

For servers or headless environments, Agent Reach uses the **xiaohongshu-mcp** backend. This is a self-contained headless-browser service that runs on `localhost:18060/mcp`. The service is accessed through the generic `mcporter` RPC client, making it suitable for automated workflows and cloud deployments where browser GUI interaction is not possible.

### xhs-cli as Legacy Fallback

The **xhs-cli** backend serves as a legacy fallback for systems where the newer tools are not yet installed. This method calls the now-unmaintained `xhs-cli` binary directly. While functional if already present, users should migrate to OpenCLI or xiaohongshu-mcp for ongoing support.

## Installing the Xiaohongshu Channel

Installation requires running the channel-specific installer, which automatically selects the appropriate backend for your detected environment.

Run the installation command:

```bash
agent-reach install --channels xiaohongshu

```

The installer function `_install_xhs_deps` in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 146-154) determines whether to configure OpenCLI, xiaohongshu-mcp, or xhs-cli based on your system capabilities.

After installation, verify the setup using the doctor command:

```bash
agent-reach doctor

```

Look for the confirmation message indicating which backend is active, such as “XiaoHongShu — OpenCLI available (reuse browser login).” If the output displays a warning, follow the printed instructions to install the OpenCLI Chrome extension or start the MCP service manually.

## Querying Xiaohongshu Data

All data fetching is performed by invoking the underlying tool directly; Agent Reach does not wrap or transform the output unless explicitly requested. The specific command depends on your active backend.

Use the following commands for common operations:

- **Search notes**: `opencli xiaohongshu search <keyword> -f yaml` (OpenCLI) or `mcporter xiaohongshu.search_feeds(keyword:"<keyword>")` (MCP)
- **Read a single note**: `opencli xiaohongshu note <note_id> -f yaml`
- **List a user’s feed**: `opencli xiaohongshu feed <user_id> -f yaml`
- **Fetch comments**: `opencli xiaohongshu comments <note_id> -f yaml`

For desktop users (OpenCLI backend), search for notes containing “travel”:

```bash
opencli xiaohongshu search travel -f yaml

```

For server environments using the MCP backend, the equivalent query uses the `mcporter` command as shown in lines 122-130 of [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py):

```bash
mcporter xiaohongshu.search_feeds(keyword:"travel") -f json

```

## Formatting Raw Output

To clean and trim raw JSON output from any backend, pipe the results through Agent Reach’s built-in formatter:

```bash
opencli xiaohongshu search travel -f json | agent-reach format xhs > tidy.json

```

The `format` command reads JSON from stdin and outputs a structured, trimmed version suitable for downstream processing.

## Programmatic Access with Python

You can embed Xiaohongshu data access directly into your Python applications by calling the underlying tools via subprocess.

For desktop environments using OpenCLI:

```python
import subprocess, json
from pathlib import Path

def run_opencli(args):
    """Run an opencli command and return parsed JSON."""
    proc = subprocess.run(
        ["opencli", "xiaohongshu"] + args,
        capture_output=True, text=True, timeout=30
    )
    proc.check_returncode()
    return json.loads(proc.stdout)

def search_notes(keyword: str):
    data = run_opencli(["search", keyword, "-f", "json"])
    # Optional: clean the raw result with Agent-Reach's formatter

    cleaned = json.loads(
        subprocess.check_output(
            ["agent-reach", "format", "xhs"], 
            input=json.dumps(data), 
            text=True
        )
    )
    return cleaned

# Example usage

if __name__ == "__main__":
    notes = search_notes("minimalism")
    Path("notes.json").write_text(
        json.dumps(notes, ensure_ascii=False, indent=2)
    )
    print("Saved", len(notes), "notes")

```

For server environments using the MCP backend:

```python
def run_mcporter(keyword):
    proc = subprocess.run(
        ["mcporter", "xiaohongshu.search_feeds", 
         f'keyword:"{keyword}"', "-f", "json"],
        capture_output=True, text=True, timeout=30
    )
    proc.check_returncode()
    return json.loads(proc.stdout)

```

## Key Source Files and Implementation Details

The following files in the Agent-Reach repository implement the Xiaohongshu integration:

- **[`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py)** – Contains the `XiaoHongShuChannel` class, including the `check` method (lines 60-96) for backend detection and the logic for invoking each backend (lines 122-130).
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – Implements the installer logic via `_install_xhs_deps` (lines 146-154), which selects and configures the appropriate backend during installation.
- **[`agent_reach/doctor.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/doctor.py)** – Runs health checks for all channels through `check_all`, including the Xiaohongshu backend verification.
- **[`agent_reach/backends/opencli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/backends/opencli.py)** – Provides generic OpenCLI helper functions used by the Xiaohongshu channel.
- **[`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py)** – Stores configuration data such as proxy settings required for server environments.

## Summary

- Agent Reach accesses Xiaohongshu data by orchestrating three upstream backends rather than implementing its own API client.
- The **doctor** routine in `XiaoHongShuChannel.check` automatically selects between OpenCLI (desktop), xiaohongshu-mcp (server), and xhs-cli (legacy) based on environment detection.
- Install the channel with `agent-reach install --channels xiaohongshu`, then verify with `agent-reach doctor`.
- Query data using backend-specific commands (`opencli` or `mcporter`), and optionally pipe results through `agent-reach format xhs` for cleaned JSON output.
- Programmatic access is available via subprocess calls to the underlying tools, with helper logic located in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py).

## Frequently Asked Questions

### Does Agent Reach include its own Xiaohongshu API credentials?

No. Agent Reach does not provide API credentials or implement direct API access to Xiaohongshu. It orchestrates existing tools that already have authentication mechanisms, such as OpenCLI (which uses your Chrome browser cookies) or xiaohongshu-mcp (which handles its own headless browser authentication).

### How does Agent Reach choose between OpenCLI and xiaohongshu-mcp?

The selection happens automatically during the `doctor` check and installation phases. The `XiaoHongShuChannel.check` method in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 60-96) probes OpenCLI first, then xiaohongshu-mcp, then xhs-cli, marking the first fully functional backend as active. Desktop environments typically select OpenCLI, while headless servers default to xiaohongshu-mcp.

### Can I use Agent Reach on a server without a GUI?

Yes. The **xiaohongshu-mcp** backend is specifically designed for headless server environments. After installing the channel, you must start the MCP service (typically on `localhost:18060/mcp`) and register it with `mcporter config add xiaohongshu http://localhost:18060/mcp`. The `agent-reach doctor` command will confirm when the service is running and accessible.

### What is the difference between `opencli` and `mcporter` commands?

`opencli` is the command-line interface for the OpenCLI backend, suitable for desktop environments where it can reuse existing browser authentication. `mcporter` is the RPC client for the Model Context Protocol (MCP) backend, used primarily in server environments to communicate with the headless xiaohongshu-mcp service. Both perform similar data operations but use different syntax and connection methods as documented in [`agent_reach/channels/xiaohongshu.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/xiaohongshu.py) (lines 122-130).