# How to Deploy xiaohongshu-mcp Using Docker Compose: Complete Setup Guide

> Deploy xiaohongshu-mcp using Docker Compose with a complete setup guide. Follow instructions to pull the image, mount volumes, and expose the port for a seamless deployment.

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

---

**Deploy `xiaohongshu-mcp` using Docker Compose by pulling the pre-built image `xpzouying/xiaohongshu-mcp`, mounting volumes for `./data` (cookies) and `./images` (uploads), and exposing port 18060.**

The `xpzouying/xiaohongshu-mcp` repository packages a Model Context Protocol (MCP) server for Xiaohongshu (Little Red Book) into a containerized Go application. When you deploy `xiaohongshu-mcp` using Docker Compose, you get a headless Chrome browser (managed by the **rod** library), persistent session storage, and a standardized MCP interface running on port 18060.

## Prerequisites and Architecture Overview

Before deploying, ensure your host has Docker Engine and Docker Compose installed. The `xiaohongshu-mcp` image is a self-contained unit that bundles:

- A compiled Go binary implementing the MCP protocol
- Headless Google Chrome and required fonts (for web automation via **rod**)
- Default configuration pointing to `/usr/bin/google-chrome`

No external database or message queue is required. The service stores state locally using bind-mounted volumes.

## Step-by-Step Docker Compose Deployment

### Download the Compose Configuration

The official Docker Compose file resides at [`docker/docker-compose.yml`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/docker/docker-compose.yml) in the repository. Download it directly:

```bash
curl -O https://raw.githubusercontent.com/xpzouying/xiaohongshu-mcp/main/docker/docker-compose.yml

```

Alternatively, clone the repository and navigate to the `docker` directory.

### Configure Volumes and Environment Variables

Create the host directories that will persist your session data and image uploads:

```bash
mkdir -p data images

```

Edit [`docker-compose.yml`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/docker-compose.yml) to review the default configuration. The file defines:

- **Image**: `xpzouying/xiaohongshu-mcp` (or the Alibaba Cloud mirror for China-based deployments)
- **Ports**: `18060:18060` exposes the MCP server on localhost
- **Volumes**:
  - `./data:/app/data` – persists [`cookies.json`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies.json) across restarts
  - `./images:/app/images` – stores images you intend to publish
- **Environment**:
  - `ROD_BROWSER_BIN=/usr/bin/google-chrome` – tells **rod** where to find Chrome
  - `COOKIES_PATH=/app/data/cookies.json` – sets the persistent cookie location
  - *(Optional)* `XHS_PROXY` – configure HTTP/HTTPS/SOCKS5 proxy for 小红书 access

### Start the Service

Launch the container in detached mode:

```bash
docker compose up -d

```

Verify the service is healthy by following the logs:

```bash
docker compose logs -f

```

You should see a message indicating the **MCP server listening on :18060**.

## Configuring Persistent Storage and Proxies

The deployment relies on two critical bind mounts to maintain state between container restarts:

- **`./data`**: Stores [`cookies.json`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies.json), which contains your authenticated session. Without this volume, you would need to re-scan the QR code every time the container restarts.
- **`./images`**: Serves as a staging area for image files you want to upload to Xiaohongshu. The MCP server reads from `/app/images` inside the container.

If you operate behind a firewall or require traffic routing through a specific egress point, set the `XHS_PROXY` environment variable in [`docker-compose.yml`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/docker-compose.yml):

```yaml
environment:
  - XHS_PROXY=http://user:pass@proxy.example.com:8080

```

## Verifying the Deployment and Logging In

Once the container reports it is listening on port 18060, the MCP server is ready to accept connections.

Connect your MCP client (such as the MCP Inspector or Claude Desktop) to `http://localhost:18060/mcp`.

Use the following workflow to authenticate:

1. Call the **`check_login_status`** tool to determine if a valid session exists in the mounted [`cookies.json`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies.json).
2. If not authenticated, invoke **`get_login_qrcode`** to generate a QR code.
3. Scan the QR code with the official 小红书 mobile app to establish a session. The cookies will be automatically written to [`/app/data/cookies.json`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main//app/data/cookies.json) and persisted on your host via the volume mount.

## Key Configuration Files Reference

Understanding the repository layout helps when customizing your deployment:

| File | Purpose |
|------|---------|
| [`docker/docker-compose.yml`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/docker/docker-compose.yml) | Service definition, volume mounts, and environment variables |
| `Dockerfile` | Multi-stage build compiling the Go binary and installing Chrome |
| [`docker/README.md`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/docker/README.md) | Extended Docker-specific documentation |
| [`README.md`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/README.md) | Project overview and MCP Inspector setup |
| [`docs/API.md`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/docs/API.md) | Complete MCP JSON-RPC method specifications |

## Summary

- **Deploy `xiaohongshu-mcp` using Docker Compose** by pulling the official image and mounting `./data` and `./images` volumes for persistence.
- The container exposes port **18060** and requires the environment variables `ROD_BROWSER_BIN` and `COOKIES_PATH` to locate Chrome and store session data.
- Authentication persists across restarts via the [`cookies.json`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies.json) file stored in the `./data` volume, eliminating the need to re-scan QR codes after container updates.
- Optional proxy support is available through the `XHS_PROXY` environment variable for restricted network environments.

## Frequently Asked Questions

### What ports need to be open to deploy xiaohongshu-mcp using Docker Compose?

The container exposes **port 18060** by default. You must map this port on your host (e.g., `18060:18060`) to allow MCP clients to connect to `http://localhost:18060/mcp`. No other inbound ports are required, though the container needs outbound internet access to reach 小红书 and download the Chrome browser during the image build.

### How do I persist login sessions when deploying xiaohongshu-mcp using Docker Compose?

Mount a host directory to `/app/data` inside the container (e.g., `./data:/app/data`). The service writes [`cookies.json`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/cookies.json) to this location, storing your authenticated session from the 小红书 QR code login. Because the file resides on your host filesystem, it survives container restarts and updates, allowing you to maintain your login state indefinitely.

### Can I use a proxy with xiaohongshu-mcp Docker deployment?

Yes. Set the `XHS_PROXY` environment variable in your [`docker-compose.yml`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/docker-compose.yml) file to route traffic through an HTTP, HTTPS, or SOCKS5 proxy. This is useful when operating behind corporate firewalls or when you need to access 小红书 from a specific geographic egress point. The proxy configuration applies to all outbound requests made by the headless Chrome browser and the Go MCP server.

### Where is the Docker Compose file located in the xiaohongshu-mcp repository?

The official Docker Compose configuration is located at **[`docker/docker-compose.yml`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/docker/docker-compose.yml)** in the `xpzouying/xiaohongshu-mcp` repository. You can download it directly via `curl` or by cloning the repository and navigating to the `docker` directory. This file contains the complete service definition, volume mounts, environment variables, and port mappings required to run the MCP server.