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

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 (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:

agent-reach install --channels xiaohongshu

The installer function _install_xhs_deps in 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:

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”:

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:

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:

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:

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:

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 – 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 – Implements the installer logic via _install_xhs_deps (lines 146-154), which selects and configures the appropriate backend during installation.
• agent_reach/doctor.py – Runs health checks for all channels through check_all, including the Xiaohongshu backend verification.
• agent_reach/backends/opencli.py – Provides generic OpenCLI helper functions used by the Xiaohongshu channel.
• 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.

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 (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 (lines 122-130).

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