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

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 in the repository. Download it directly:

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:

mkdir -p data images

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

docker compose up -d

Verify the service is healthy by following the logs:

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

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.
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 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	Service definition, volume mounts, and environment variables
Dockerfile	Multi-stage build compiling the Go binary and installing Chrome
docker/README.md	Extended Docker-specific documentation
README.md	Project overview and MCP Inspector setup
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 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 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 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 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.

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