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

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

   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:

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 file serves as the entry point, parsing flags and initializing the AppServer, while cmd/login/main.go builds the QR-code authentication helper.

Option 3: Docker Deployment

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

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:

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:

./xiaohongshu-login-<platform>

Scan the displayed QR code with the Xiaohongshu mobile app. The tool persists cookies to ./data/cookies.json (handled by cookies/cookies.go) for session reuse.

Step 2: Configure Headless Mode and Browser Path

As implemented in 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 wraps go-rod and respects these configuration values.

Step 3: Start the Server

Launch the MCP server with default settings:

./xiaohongshu-mcp-<platform>

The AppServer struct in 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, 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:

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:

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

Call tools using JSON-RPC:

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, while 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 via cookies/cookies.go.
• The server architecture centers on main.go (entry point), app_server.go (HTTP server wiring), and mcp_server.go (13 MCP tools registration).
• Configuration options in 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 file created by 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 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) 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 package stores this value, and browser/browser.go initializes go-rod with the specified path instead of auto-downloading.

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