# How to Set Up the xiaohongshu-mcp Server: Complete Installation Guide

> Learn how to set up the xiaohongshu-mcp server with this complete installation guide. Deploy this Go-based HTTP service easily via binaries, Docker, or source for automating Xiaohongshu.

- Repository: [zy/xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)
- Tags: how-to-guide
- Published: 2026-03-09

---

**The xiaohongshu-mcp server is a Go-based HTTP service that exposes 13 Model-Context-Protocol tools and REST endpoints for automating Xiaohongshu, deployable via pre-compiled binaries, Docker, or source compilation on port 18060.**

The **xiaohongshu-mcp** project (`xpzouying/xiaohongshu-mcp`) implements a self-contained automation server using the `go-rod` headless browser library to drive Chromium and the official `go-sdk/mcp` library to register tools. According to the source code in [`main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main.go), the server initializes configuration, creates the `XiaohongshuService`, and starts an HTTP listener on **port 18060** by default.

## Prerequisites

Before installing, ensure your environment meets these requirements:

- **Go 1.22 or later** (required only for building from source)
- **Chromium or Chrome** (automatically downloaded on first run, or specify a custom path via `ROD_BROWSER_BIN` or the `--bin` flag)
- **Network access** to download the Chromium binary (~150 MB) and reach Xiaohongshu servers
- **Docker** (optional, for containerized deployment)

## Installation Methods

### Option 1: Pre-compiled Binaries (Recommended)

The fastest way to deploy the xiaohongshu-mcp server is using the release binaries:

1. Download the appropriate binary from the [GitHub Releases](https://github.com/xpzouying/xiaohongshu-mcp/releases) page:
   - macOS Apple Silicon: `xiaohongshu-mcp-darwin-arm64`
   - macOS Intel: `xiaohongshu-mcp-darwin-amd64`
   - Windows x64: `xiaohongshu-mcp-windows-amd64.exe`
   - Linux x64: `xiaohongshu-mcp-linux-amd64`

2. Make the binary executable (POSIX systems):

   ```bash
   chmod +x xiaohongshu-mcp-<platform>
   ```

3. Download the corresponding **login helper** binary (named `xiaohongshu-login-<platform>`) to authenticate with Xiaohongshu.

### Option 2: Build from Source

Clone the repository and compile the binaries manually:

```bash
git clone https://github.com/xpzouying/xiaohongshu-mcp.git
cd xiaohongshu-mcp
go build -o xiaohongshu-mcp ./main.go
go build -o xiaohongshu-login ./cmd/login/main.go

```

The [`main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main.go) file serves as the entry point, parsing flags and initializing the `AppServer`, while [`cmd/login/main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cmd/login/main.go) builds the QR-code authentication helper.

### Option 3: Docker Deployment

For the most portable setup, use the official Docker image:

```bash
docker pull xpzouying/xiaohongshu-mcp
docker run -d \
  -p 18060:18060 \
  -v $(pwd)/data:/app/data \
  --name xhs-mcp \
  xpzouying/xiaohongshu-mcp

```

Alternatively, use Docker Compose with the provided configuration:

```bash
wget https://raw.githubusercontent.com/xpzouying/xiaohongshu-mcp/main/docker/docker-compose.yml
docker compose up -d

```

The Docker image automatically installs Chromium inside the container, eliminating the need for external browser binaries.

## Initial Configuration and Authentication

The xiaohongshu-mcp server requires valid Xiaohongshu cookies to function. The authentication flow uses a separate login helper to generate QR codes.

### Step 1: Run the Login Helper

Execute the login binary to open a QR-code window:

```bash
./xiaohongshu-login-<platform>

```

Scan the displayed QR code with the Xiaohongshu mobile app. The tool persists cookies to [`./data/cookies.json`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/./data/cookies.json) (handled by [`cookies/cookies.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies/cookies.go)) for session reuse.

### Step 2: Configure Headless Mode and Browser Path

As implemented in [`configs/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/configs/browser.go), the server supports two global configuration flags:

- **Headless mode**: Controlled via `configs.InitHeadless` (default `true`). Disable with `-headless=false` to see the browser UI.
- **Custom binary**: Set `ROD_BROWSER_BIN` environment variable or use `--bin /usr/bin/chrome` to specify a custom Chromium path.

The browser abstraction in [`browser/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser/browser.go) wraps `go-rod` and respects these configuration values.

### Step 3: Start the Server

Launch the MCP server with default settings:

```bash
./xiaohongshu-mcp-<platform>

```

The `AppServer` struct in [`app_server.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/app_server.go) initializes the MCP server (via `InitMCPServer`), configures the Gin router (via `setupRoutes`), and binds to `:18060`.

## Verifying the Installation

Confirm the server is operational using these checks:

| Check | Command | Expected Result |
|-------|---------|-----------------|
| Health endpoint | `curl http://localhost:18060/health` | `OK` |
| Login status | `curl http://localhost:18060/api/v1/login/status` | JSON with `"is_logged_in": true` |
| MCP tools list | Connect via MCP inspector to `http://localhost:18060/mcp` | 13 tools (e.g., `check_login_status`, `publish_content`) |

The MCP endpoint (`/mcp` and `/mcp/*path`) is served by `go-sdk/mcp.NewStreamableHTTPHandler` as configured in [`mcp_server.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go), which registers all tools with panic-recovery wrappers.

## Using the Server

### REST API Publishing

Publish content directly via the REST API exposed in [`routes.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go):

```bash
curl -X POST http://localhost:18060/api/v1/publish \
  -H "Content-Type: application/json" \
  -d '{
    "title": "MCP Test Post",
    "content": "Automated content via REST",
    "images": ["/path/to/image.jpg"],
    "tags": ["tech", "automation"],
    "is_original": true,
    "visibility": "公开可见"
  }'

```

### MCP Client Integration

Register the server with Claude Code or other MCP clients:

```bash
claude mcp add --transport http xiaohongshu-mcp http://localhost:18060/mcp

```

Call tools using JSON-RPC:

```bash
claude mcp call publish_content \
  '{"title": "MCP Demo", "content": "via MCP", "images": ["/path/to/img.jpg"]}'

```

The business logic resides in `xiaohongshu/*.go` files (login, publish, feed crawling) and [`service.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/service.go), while [`pkg/downloader/images.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/pkg/downloader/images.go) handles remote image fetching.

## Summary

- The **xiaohongshu-mcp** server requires **Go 1.22+** for source builds or uses **Docker** for containerized deployment, listening on **port 18060** by default.
- Authentication requires running the **login helper** binary to scan a QR code, storing cookies in [`./data/cookies.json`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/./data/cookies.json) via [`cookies/cookies.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies/cookies.go).
- The server architecture centers on [`main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main.go) (entry point), [`app_server.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/app_server.go) (HTTP server wiring), and [`mcp_server.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go) (13 MCP tools registration).
- Configuration options in [`configs/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/configs/browser.go) control **headless mode** (default `true`) and custom Chromium binary paths via flags or environment variables.
- Both **REST API** (`/api/v1/*`) and **MCP protocol** (`/mcp`) endpoints provide access to Xiaohongshu automation features.

## Frequently Asked Questions

### How do I reset stale cookies or login sessions?

Use the `delete_cookies` MCP tool or send a `DELETE` request to `/api/v1/login/cookies`. This removes the [`./data/cookies.json`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/./data/cookies.json) file created by [`cookies/cookies.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies/cookies.go). Then re-run the `xiaohongshu-login` helper to generate fresh authentication cookies.

### Can I run the server without headless mode for debugging?

Yes. Start the server with the `-headless=false` flag to disable headless mode. The [`browser/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser/browser.go) wrapper passes this flag to `go-rod`, opening a visible Chromium window. This is useful for debugging CI environments or troubleshooting browser automation issues.

### What is the difference between the REST API and MCP endpoints?

The **REST API** (`/api/v1/*` routes defined in [`routes.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go)) provides conventional HTTP JSON endpoints for direct integration. The **MCP endpoint** (`/mcp` served via `go-sdk/mcp.NewStreamableHTTPHandler`) exposes the same 13 tools via the Model-Context-Protocol, enabling AI assistants like Claude and Cursor to discover and invoke capabilities automatically.

### How do I specify a custom Chromium binary path?

Set the `ROD_BROWSER_BIN` environment variable (e.g., `export ROD_BROWSER_BIN=/usr/bin/chromium`) or use the `--bin` command-line flag when starting the server. The [`configs/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/configs/browser.go) package stores this value, and [`browser/browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/browser/browser.go) initializes `go-rod` with the specified path instead of auto-downloading.