xiaohongshu-mcp 接入 xiaozhi 详细文档

一、背景与目标

将 xiaohongshu-mcp（小红书 MCP 服务，基于 HTTP 协议）接入 xiaozhi 语音助手，使其能够通过语音控制发布小红书内容。

二、架构说明

2.1 整体架构

复制代码

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  小智语音助手     │ ───► │  xiaozhi.me     │ ───► │  mcp_pipe.py    │ ───► │  mcp_proxy      │
│  (用户语音输入)   │      │  (云端MCP网关)   │      │  (桥接工具)      │      │  (协议转换)      │
└─────────────────┘      └─────────────────┘      └─────────────────┘      └─────────────────┘
                                                                                  │
                                                                                  ▼
                                                                         ┌─────────────────┐
                                                                         │ xiaohongshu-mcp │
                                                                         │  (HTTP :18060)  │
                                                                         └─────────────────┘

2.2 各组件职责

组件	协议	作用
xiaozhi.me	WebSocket	云端MCP接入点，接收语音端请求
mcp_pipe.py	stdio + WebSocket	桥接工具，将stdio转WebSocket
mcp_proxy	stdio + HTTP	协议转换，将HTTP转stdio
xiaohongshu-mcp	HTTP	小红书MCP服务，提供发布API

2.3 传输协议转换过程

xiaohongshu-mcp 使用 streamablehttp 协议，监听 :18060
mcp_proxy 将 streamablehttp 转换为 stdio
mcp_pipe.py 通过 stdio 与 mcp_proxy 通信，并将数据通过 WebSocket 发送到 xiaozhi.me

三、详细接入步骤

3.1 环境准备

bash 复制代码

# 下载 xiaohongshu-mcp
cd ~/下载
wget https://github.com/xpzouying/xiaohongshu-mcp/releases/...
chmod +x xiaohongshu-mcp-linux-amd64

# 确认 mcp_proxy 已安装
pip show mcp-proxy
# Version: 0.11.0

3.2 配置 mcp_config.json

文件路径：~/下载/mcp-calculator-main/mcp_config.json

json 复制代码

{
  "mcpServers": {
    "xhs": {
      "type": "streamablehttp",
      "url": "http://localhost:18060/mcp"
    }
  }
}

3.3 启动 xiaohongshu-mcp 服务

bash 复制代码

cd ~/下载

# 启动服务（后台运行）
./xiaohongshu-mcp-linux-amd64 -port=:18060 -headless=true &

# 确认服务运行
curl -s http://localhost:18060/mcp
# 输出: GET requires an active session (表示服务正常)

3.4 确保登录态有效

bash 复制代码

# 检查登录状态
./xiaohongshu-login-linux-amd64
# 输出: INFO[0004] 当前登录状态: true

# 如果登录态失效，需要重新登录
# 登录cookie存放在 ~/xhs_cookies/xiaohongshu_cookies.json

3.5 获取 xiaozhi MCP 接入点

登录 xiaozhi.me
进入智能体配置页面
右下角获取专属 MCP 接入点 WebSocket URL

格式类似：

复制代码

wss://api.xiaozhi.me/mcp/?token=eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...

3.6 启动桥接服务

bash 复制代码

cd ~/下载/mcp-calculator-main

# 重要：必须清除代理环境变量，否则 mcp_proxy 会因 socks:// 代理报错
env -i \
  HOME=$HOME \
  PATH=$PATH \
  MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=你的token" \
  http_proxy= https_proxy= ALL_PROXY= no_proxy= \
  python3 mcp_pipe.py

3.7 验证连接

成功连接的日志：

复制代码

2026-05-13 14:30:12,351 - MCP_PIPE - INFO - Starting servers: xhs
2026-05-13 14:30:12,351 - MCP_PIPE - INFO - [xhs] Connecting to WebSocket server...
2026-05-13 14:30:13,546 - MCP_PIPE - INFO - [xhs] Successfully connected to WebSocket server
2026-05-13 14:30:13,549 - MCP_PIPE - INFO - [xhs] Started server process: /usr/bin/python3 -m mcp_proxy --transport streamablehttp http://localhost:18060/mcp
[I 2026-05-13 14:30:13,953.953 mcp.client.streamable_http] Received session ID: MIJJOZFGRVU5BSBI2B5YHBFCJF
[I 2026-05-13 14:30:13,993.993 mcp.server.lowlevel.server] Processing request of type ListToolsRequest

四、工具使用示例

4.1 小红书 MCP 工具

工具名称	功能	主要参数
publish_content	发布图文内容	title, content, images, tags
login_status	检查登录状态	-

4.2 发布内容参数说明

json 复制代码

{
  "title": "内容标题（最多20个中英文单词）",
  "content": "正文内容（不含#标签）",
  "images": ["图片URL列表", "至少1张图片"],
  "tags": ["话题标签", "如: 美食, 旅行"],
  "is_original": true,
  "schedule_at": "2024-01-20T10:30:00+08:00"
}

五、图片处理解决方案

5.1 问题

语音控制时，用户无法直接提供图片URL。

5.2 解决方案

方案1：使用 test_photo 工具

已创建测试图片搜索工具，位于 /home/user/xiaozhi/src/mcp/tools/test_photo/

python 复制代码

# 工具列表
test_photo.take_photo    # 返回测试图片URL
test_photo.search_image   # 根据关键词搜索图片URL

方案2：机器人拍照

调用 camera 工具拍照，照片保存后使用本地路径。

5.3 已集成的 test_photo 工具

文件结构：

复制代码

/home/user/xiaozhi/src/mcp/tools/test_photo/
├── __init__.py      # 包导出
├── manager.py       # 工具管理器
└── tools.py         # 工具实现

注册位置：/home/user/xiaozhi/src/mcp/mcp_server.py

六、常见问题与解决

6.1 代理冲突

错误信息：

复制代码

ValueError: Unknown scheme for proxy URL URL('socks://127.0.0.1:7897/')

解决方法： 使用 env -i 清除所有代理环境变量

bash 复制代码

env -i HOME=$HOME PATH=$PATH http_proxy= https_proxy= ALL_PROXY= no_proxy= python3 mcp_pipe.py

6.2 登录态过期

现象： 发布成功但小红书后台无内容

解决方法：

bash 复制代码

# 重新登录
cd ~/下载 && ./xiaohongshu-login-linux-amd64

6.3 Session 初始化错误

错误信息：

复制代码

method "tools/list" is invalid during session initialization

解决方法： 先发送 initialize 请求，再调用工具

bash 复制代码

# 1. 初始化
curl -X POST http://localhost:18060/mcp -d '{"jsonrpc":"2.0","method":"initialize",...}'

# 2. 列工具
curl -X POST http://localhost:18060/mcp -d '{"jsonrpc":"2.0","method":"tools/list",...}'

七、文件清单

文件路径	说明
`~/下载/xiaohongshu-mcp-linux-amd64`	小红书MCP服务主程序
`~/下载/xiaohongshu-login-linux-amd64`	登录工具
`~/下载/mcp-calculator-main/mcp_config.json`	MCP服务配置
`~/下载/mcp-calculator-main/mcp_pipe.py`	桥接工具
`~/xhs_cookies/xiaohongshu_cookies.json`	登录cookies
`/home/user/xiaozhi/src/mcp/tools/test_photo/`	测试图片工具

八、后续优化建议

实现真实图片搜索 - 集成Unsplash/Pexels等API
拍照集成 - 对接机器人摄像头，拍照后直接用于发布
自动登录检测 - 定时检查登录态，过期自动提醒
错误处理优化 - 完善异常情况的用户提示
多账号支持 - 支持切换不同小红书账号