Configuring xiaohongshu-mcp: Complete Guide to Environment Variables

xiaohongshu-mcp supports three environment variables—ROD_BROWSER_BIN, COOKIES_PATH, and XHS_PROXY—to configure the Chrome binary path, cookies file location, and HTTP proxy settings without modifying command-line flags.

The xpzouying/xiaohongshu-mcp project provides a Model Context Protocol (MCP) server for interacting with Xiaohongshu (Little Red Book). Understanding how to configure this tool via environment variables allows you to customize browser behavior, manage authentication persistence, and route traffic through proxies in containerized or automated deployments.

Available Environment Variables for xiaohongshu-mcp

The application reads configuration from the environment at startup, overlaying these values atop default settings and command-line arguments.

ROD_BROWSER_BIN: Chrome Binary Path

The ROD_BROWSER_BIN variable specifies the absolute path to the Chrome or Chromium binary used by the headless browser driver (Rod).

• Purpose: Overrides the default browser discovery mechanism when the -bin flag is not provided
• Default: Empty string (automatic binary detection)
• Source: [main/main.go lines 23–24](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main/main.go#L23)

If this variable is unset and no -bin flag is passed, the Rod driver attempts to locate a suitable Chrome installation automatically.

COOKIES_PATH: Persistent Cookies Location

The COOKIES_PATH variable defines the filesystem location for the cookies.json file, enabling persistent authentication across server restarts.

• Purpose: Allows storing cookies outside the working directory for security or organizational requirements
• Default: "cookies.json" in the current working directory
• Source: [cookies/cookies.go lines 69–72](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies/cookies.go#L69)

This file stores serialized HTTP cookies from Xiaohongshu sessions, eliminating the need to re-authenticate on every server launch when the file exists and contains valid session data.

XHS_PROXY: HTTP/HTTPS Proxy Configuration

The XHS_PROXY variable routes all browser traffic through a specified HTTP or HTTPS proxy, useful for debugging, regional access, or network isolation.

• Purpose: Configures the Rod browser to tunnel connections through an intermediary proxy server
• Default: Not set (direct connection)
• Source: [browser/browser.go lines 51–54](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser/browser.go#L51)

The proxy URL should follow standard format: http://host:port or http://username:password@host:port for authenticated proxies.

Practical Configuration Examples

Setting the Chrome Binary Path

Configure a specific Chrome installation when the automatic detection fails or when using a non-standard installation location:

export ROD_BROWSER_BIN="/usr/bin/google-chrome-stable"
./xiaohongshu-mcp -headless=true

Using a Custom Cookies File

Store authentication data in a dedicated configuration directory:

export COOKIES_PATH="/home/user/.config/xiaohongshu-mcp/cookies.json"
./xiaohongshu-mcp

Routing Traffic Through a Proxy

Debug network requests or bypass regional restrictions:

export XHS_PROXY="http://username:password@proxy.example.com:3128"
./xiaohongshu-mcp

Combined Configuration

Deploy with all three variables for a production container environment:

export ROD_BROWSER_BIN="/opt/chrome/chrome"
export COOKIES_PATH="/data/xhs/cookies.json"
export XHS_PROXY="http://proxy.local:8080"

./xiaohongshu-mcp -headless=false -port=:8080

Implementation Details

Environment variables are evaluated once at startup when the application initializes its subsystems. The main() function in [main/main.go](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main/main.go) orchestrates this process, passing configuration values to the browser and cookie management packages.

The browser construction logic in [browser/browser.go](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser/browser.go) checks for XHS_PROXY when configuring the Rod launcher, while [cookies/cookies.go](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies/cookies.go) resolves the cookie file path using COOKIES_PATH during initialization.

Summary

• ROD_BROWSER_BIN specifies the Chrome/Chromium binary location when automatic detection is insufficient
• COOKIES_PATH defines the persistent storage location for authentication cookies, defaulting to ./cookies.json
• XHS_PROXY configures HTTP/HTTPS proxy routing for all browser traffic
• Variables are read once at startup in main.go, browser.go, and cookies.go respectively

Frequently Asked Questions

What is the default cookies file location if COOKIES_PATH is not set?

If the COOKIES_PATH environment variable is not defined, xiaohongshu-mcp defaults to cookies.json in the current working directory. This fallback is implemented in [cookies/cookies.go](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies/cookies.go) for local debugging convenience.

Can I use environment variables alongside command-line flags?

Yes. Environment variables provide default values that command-line flags can override. For example, if ROD_BROWSER_BIN is set but you also pass the -bin flag, the command-line argument takes precedence. This layering is handled in the flag parsing logic within [main/main.go](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main/main.go).

Does xiaohongshu-mcp support SOCKS5 proxies via XHS_PROXY?

The current implementation in [browser/browser.go](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser/browser.go) expects an HTTP or HTTPS proxy URL for the XHS_PROXY variable. SOCKS5 support is not explicitly implemented in the source code; attempting to use a socks5:// scheme may result in connection errors.

When are environment variables loaded during the application lifecycle?

Environment variables are evaluated once during the initialization phase before the MCP server starts accepting connections. Specifically, ROD_BROWSER_BIN is checked when parsing flags in main(), COOKIES_PATH is resolved when the cookie manager initializes, and XHS_PROXY is applied when constructing the browser launcher. Changes to environment variables require a server restart to take effect.

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