MCP 服务器

xhs-read-mcp

A read-only MCP server for Xiaohongshu that enables searching notes, fetching details and comments, with QR code login support.

README

xhs-read-mcp

本地单用户、只读的小红书 MCP 服务。项目使用 Python、Playwright Chromium 和官方 MCP Python SDK，通过正常加载小红书网页并读取 window.__INITIAL_STATE__ 提供结构化数据。

功能范围

检查网页登录状态。
返回二维码并在后台等待扫码。
原子保存和恢复 Playwright storage state。
清除本机登录状态。
按关键词和网页筛选项读取初始搜索结果。
使用搜索结果配套的 note_id 和 xsec_token 读取详情。
返回初始评论，或按上限滚动加载更多父评论。
默认 stdio，可选 Streamable HTTP。

本项目不发布内容、不点赞、不收藏、不关注、不发表评论，不调用需要逆向签名的私有 API，也不绕过验证码或风控。

环境要求

Python 3.11 或更高版本。
可运行 Chromium 的本机环境。
能正常访问小红书网页的网络。

使用 Docker Compose 部署时，本机不需要安装 Python 或 Chromium，只需要 Docker Compose v2。

安装

Windows PowerShell 示例：

git clone https://github.com/KZI-22/xhs_mcp.git
cd xhs_mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m playwright install chromium

也可以使用 uv 安装；项目使用标准 pyproject.toml，不依赖特定包管理器。

Docker Compose 一键部署

仓库镜像由 GitHub Actions 自动构建并发布到 ghcr.io/kzi-22/xhs_mcp。下载本仓库的 compose.yaml 后运行：

仓库维护者首次发布镜像后，需要在 GitHub Package 设置中将 xhs_mcp 的可见性改为 Public；否则匿名用户无法通过 Compose 拉取镜像。

docker compose up -d
docker compose logs xhs-mcp

首次启动会自动生成 MCP Bearer Token，并将 Token 和访问地址写入容器日志。默认访问地址：

http://127.0.0.1:8765/mcp

调用方需要发送日志中显示的 Token：

Authorization: Bearer <token>

二维码登录仍通过 xhs_start_login 返回，不需要为容器配置桌面或 VNC。登录状态和自动生成的 Token 保存在 xhs-data Docker Volume 中，容器升级或重启不会丢失。

更新镜像：

docker compose pull
docker compose up -d

默认 Compose 只把端口发布到宿主机 127.0.0.1。如需远程访问，应使用 HTTPS 反向代理，并同步配置允许的 Host 和 Origin；不要把明文 Bearer Token 暴露在公网 HTTP 上。

启动

stdio（默认）

xhs-read-mcp

或：

python -m xhs_read_mcp --transport stdio

stdio 模式下 stdout 只用于 MCP 协议，程序日志写入 stderr。

通用 MCP 客户端配置示意：

{
  "command": "D:\\path\\to\\.venv\\Scripts\\python.exe",
  "args": ["-m", "xhs_read_mcp"],
  "cwd": "D:\\path\\to\\xhs-read-mcp"
}

Streamable HTTP

xhs-read-mcp --transport streamable-http

默认地址：

http://127.0.0.1:8765/mcp

服务默认启用 DNS rebinding 防护，只监听本机回环地址。若显式绑定非回环地址，必须同时设置：

XHS_MCP_ALLOW_NON_LOOPBACK=true
XHS_MCP_AUTH_TOKEN=<strong-random-token>

此模式只提供静态 Bearer 边界，不等同于远程多用户 OAuth 架构。

MCP 工具

工具	作用
`xhs_check_login`	检查已保存登录状态是否有效
`xhs_start_login`	创建或复用二维码登录会话
`xhs_get_login_status`	根据 `login_id` 查询扫码状态
`xhs_cancel_login`	取消扫码会话
`xhs_logout`	清除本机状态并重置浏览器上下文
`xhs_search_notes`	搜索首次加载的笔记结果
`xhs_get_note_detail`	读取详情及可选评论

成功结果通过 MCP structuredContent 返回。整体失败使用 isError=true，并返回稳定错误码；局部评论加载失败等情况进入 warnings。

配置

配置优先级：

CLI > 环境变量 > .env > 默认值

常用环境变量：

变量	默认值
`XHS_MCP_TRANSPORT`	`stdio`
`XHS_MCP_HOST`	`127.0.0.1`
`XHS_MCP_PORT`	`8765`
`XHS_MCP_PATH`	`/mcp`
`XHS_MCP_AUTH_TOKEN`	空
`XHS_MCP_ALLOW_NON_LOOPBACK`	`false`
`XHS_MCP_ALLOWED_HOSTS`	空，逗号分隔
`XHS_MCP_ALLOWED_ORIGINS`	空，逗号分隔
`XHS_BROWSER_HEADLESS`	`true`
`XHS_BROWSER_PATH`	Playwright 管理的 Chromium
`XHS_BROWSER_CHANNEL`	空
`XHS_PROXY`	空
`XHS_AUTH_STATE_PATH`	平台用户数据目录
`XHS_MAX_CONCURRENT_OPERATIONS`	`2`
`XHS_LOGIN_TIMEOUT_SECONDS`	`240`
`XHS_STATUS_TIMEOUT_SECONDS`	`30`
`XHS_SEARCH_TIMEOUT_SECONDS`	`60`
`XHS_DETAIL_TIMEOUT_SECONDS`	`60`
`XHS_COMMENT_TIMEOUT_SECONDS`	`300`
`XHS_TIMEZONE`	`Asia/Shanghai`
`XHS_LOG_LEVEL`	`INFO`

Windows 默认状态文件：

%LOCALAPPDATA%\xhs-read-mcp\storage_state.json

该文件包含敏感登录状态，不应上传、分享或提交到版本控制。xhs_logout 只删除本机状态，不声称吊销小红书服务器端 Cookie。

测试

默认单元测试，不访问小红书，也不启动 Chromium：

python -m pytest

本地 Chromium 集成测试，不访问小红书：

python -m pytest -m browser

真实页面冒烟测试必须显式开启：

$env:XHS_RUN_LIVE_TESTS="1"
python -m pytest -m live_xhs

真实测试会访问小红书，可能需要扫码，也可能受到网页改版或风控影响。

架构

MCP tools
    -> XhsReadService
        -> LoginAction / SearchAction / FeedDetailAction / CommentLoader
            -> BrowserManager / AuthStateStore / PageContract
                -> Playwright Chromium
                    -> 小红书 DOM 与 window.__INITIAL_STATE__

一个 MCP 进程长期运行一个 Chromium 和一个共享登录 BrowserContext；每次普通调用使用独立 Page，默认最多两个并发浏览器操作。