setup-xhs-mcp

Project repository:https://github.com/xpzouying/xiaohongshu-mcp

Execution flow

1. Check service status

Check whether xiaohongshu-mcp is already running (note: the MCP endpoint only accepts POST; GET returns 405, so you cannot use -f to determine this):

curl -so /dev/null http://localhost:18060/mcp && echo "running" || echo "not running"

• Already running → record the address http://localhost:18060/mcpand skip to step 3
• Not running → ask the user: is the service deployed at another address/port?
  • User provides an address → after verifying reachability, skip to step 3
  • Not deployed → go to step 2

2. Deploy the service

Confirm the operating system (macOS / Linux / Windows) and whether Docker is already installed.

Option 1: Docker Compose (recommended)

The Docker image includes Chrome and Chinese fonts built in, so no additional configuration is needed.

# 下载 docker-compose.yml
wget https://raw.githubusercontent.com/xpzouying/xiaohongshu-mcp/main/docker/docker-compose.yml

# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f

Image source:

• Docker Hub (default):xpzouying/xiaohongshu-mcp
• Alibaba Cloud (recommended in China):crpi-hocnvtkomt7w9v8t.cn-beijing.personal.cr.aliyuncs.com/xpzouying/xiaohongshu-mcp

How to switch: edit docker-compose.yml, comment out the default image line, and uncomment the Alibaba Cloud image line.

Data persistence:

• ./data — cookies login state
• ./images — mount directory for publishing images

Option 2: Download the binary

Download from GitHub Releases:https://github.com/xpzouying/xiaohongshu-mcp/releases/latest

curl -s https://api.github.com/repos/xpzouying/xiaohongshu-mcp/releases/latest | grep browser_download_url

Note: the binary method requires Chrome or Chromium to already be installed on the local machine.

Option 3: Compile from source

Not recommended; suitable only for Go developers. Refer to the project repository README.

After deployment is complete, use curl to confirm the service has started, then proceed to step 3.

3. Check MCP connection configuration

Check whether the current client is already configured with the xiaohongshu MCP connection.

Claude Code: read ~/.claude/settings.json and the project-level .claude/settings.json, and look for mcpServers to see whether there is a xiaohongshu configuration.

• Configured and the address is correct → skip to step 5
• Configured but the address does not match → correct the address
• Not configured → go to step 4

4. Configure the MCP connection

Ask the user:

Connection address: if step 1 has already confirmed a reachable address, use that address as the default value; otherwise default to http://localhost:18060/mcp。

Client in use：

Claude Code：

claude mcp add xiaohongshu --transport http <地址>

or write to the configuration file:

• Global:~/.claude/settings.json
• Project-level:.claude/settings.json

{
  "mcpServers": {
    "xiaohongshu": {
      "url": "http://localhost:18060/mcp"
    }
  }
}

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "xiaohongshu": {
      "url": "http://localhost:18060/mcp"
    }
  }
}

Other clients: inform the user of the MCP service address and let the user configure it themselves according to the client documentation.

5. Verification and tips

1. Prompt the user to restart the current session — after MCP configuration changes, the client must be restarted to load the new MCP tools
2. After restart, call check_login_status to verify the connection is normal
3. Verification succeeds → guide the user to use /xhs-login to complete QR code login

Environment variables (optional)

• XHS_PROXY — HTTP/HTTPS/SOCKS5 proxy address
• ROD_BROWSER_BIN — custom Chromium path
• HEADLESS — headless mode switch

Failure handling

Scenario	Handling
Docker is not installed	Recommend installing Docker or switching to the binary method
Pulling images domestically is slow	Switch to the Alibaba Cloud image source
Port 18060 is occupied	Check for existing processes, or change the port
Chrome is not installed (binary method)	Guide the installation of Chrome or switch to the Docker method
The tool is still unavailable after the configuration is written	Prompt to restart the client session
There is an existing configuration but the address is wrong	Correct the address and restart