social-mcp/README.zh-CN.md at ed7fbdd5c25867947e9387665df7844c64fb20eb

kurihada/social-mcp

Fork 0

Files

T

kurihada ed7fbdd5c2 增强详情与评论MCP：支持URL自动解析并为子评论引入Keyset分页

2026-03-03 13:10:14 +08:00

8.2 KiB

Raw Blame History

English README

一个面向社交媒体自动化的服务，既提供 MCP（Model Context Protocol）工具能力，也提供 REST API。当前支持平台：小红书。

功能特性

小红书 22 个 MCP 工具（登录、浏览、发布、互动、通知、自动化）
带 Bearer Token 鉴权与按路由限流的 REST API
基于 rebrowser-playwright 的浏览器自动化，按平台串行队列执行
文件型 Cookie 持久化（0600 权限、原子写入）
通知任务状态入库 SQLite（$COOKIE_DIR/xiaohongshu/automation.db），保障自动回复幂等
Web 控制台（React + Vite）：登录、内容浏览、发布、接口测试
安全控制：Token 常量时间比对、绑定地址安全门、错误信息脱敏、日志字段脱敏
支持 Docker 部署
插件化平台架构，便于扩展更多平台

快速开始

前置要求

Node.js >= 22.0.0
pnpm

安装与运行（后端）

# 安装依赖
pnpm install

# 首次安装 Playwright Chromium
npx playwright install chromium

# 构建后端
pnpm build

# 启动服务
pnpm start

本地默认监听地址：http://127.0.0.1:9527。
首次启动会在控制台打印 REST API Bearer Token，并保存到 ~/.social-mcp/.api-token。

构建并启用 Web 控制台

# 构建后端 + 前端
pnpm build:all

# 启动服务（会同时托管 dashboard）
pnpm start

开发命令

# 后端 watch 构建
pnpm dev

# 前端开发服务器
pnpm dev:web

# 类型检查
pnpm lint

# 测试
pnpm test

MCP 集成

Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "social-mcp": {
      "url": "http://127.0.0.1:9527/sse"
    }
  }
}

MCP 工具列表（小红书）

工具名	说明
`xhs_check_login`	检查登录状态
`xhs_get_login_qrcode`	获取扫码登录二维码
`xhs_delete_cookies`	删除 Cookie 并重置登录状态
`xhs_list_feeds`	获取推荐流
`xhs_search`	关键词搜索笔记（支持筛选）
`xhs_get_feed_detail`	获取笔记详情（支持直接传笔记 URL）
`xhs_get_sub_comments`	拉取某条父评论的子评论（Keyset 游标分页）
`xhs_get_user_profile`	获取用户主页及近期笔记（支持直接传主页 URL）
`xhs_list_my_notes`	获取当前账号已发布笔记列表
`xhs_publish_image`	发布图文笔记
`xhs_publish_video`	发布视频笔记
`xhs_post_comment`	发表评论
`xhs_reply_comment`	回复评论
`xhs_set_like_state`	设置点赞状态（幂等）
`xhs_set_favorite_state`	设置收藏状态（幂等）
`xhs_get_unprocessed_notifications`	从本地 SQLite 获取“未处理”通知任务
`xhs_mark_notification_task`	手动标记通知任务状态（new/pending/ignored/replied/failed）
`xhs_mark_notification_tasks`	批量标记通知任务状态
`xhs_list_failed_notification_tasks`	获取失败通知任务列表（用于排障/重试）
`xhs_retry_notification_task`	按 fingerprint 重试失败通知任务
`xhs_retry_notification_tasks`	批量重试失败通知任务
`xhs_reply_notification`	对通知进行回复

REST API

所有 /api/* 接口都需要：

Authorization: Bearer <token>
POST 请求需设置 Content-Type: application/json

示例：

# 查询登录状态
curl -H "Authorization: Bearer <token>" \
  http://127.0.0.1:9527/api/xhs/login/status

# 搜索笔记
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"travel","filters":{"sort":"popularity_descending"}}' \
  http://127.0.0.1:9527/api/xhs/search

接口清单

读接口限流：60/min（按 IP）
写接口限流：10/min（按 IP）

方法	路径	说明	限流
`GET`	`/api/xhs/login/status`	检查登录状态	60/min
`GET`	`/api/xhs/login/qrcode`	获取二维码	60/min
`DELETE`	`/api/xhs/login/cookies`	删除 Cookie	10/min
`GET`	`/api/xhs/login/cookie-check`	检查本地 Cookie 文件是否存在	60/min
`GET`	`/api/xhs/feeds`	获取推荐流	60/min
`POST`	`/api/xhs/search`	搜索笔记	60/min
`POST`	`/api/xhs/feeds/detail`	获取笔记详情	60/min
`POST`	`/api/xhs/feeds/sub-comments`	拉取子评论	60/min
`POST`	`/api/xhs/user/profile`	获取用户主页	60/min
`GET`	`/api/xhs/my-notes`	获取我的笔记	60/min
`POST`	`/api/xhs/publish/image`	发布图文	10/min
`POST`	`/api/xhs/publish/video`	发布视频	10/min
`POST`	`/api/xhs/comment`	发表评论	10/min
`POST`	`/api/xhs/comment/reply`	回复评论	10/min
`POST`	`/api/xhs/like`	点赞切换	10/min
`POST`	`/api/xhs/favorite`	收藏切换	10/min
`GET`	`/api/xhs/notifications/comments`	获取评论通知	60/min
`GET`	`/api/xhs/notifications/unprocessed`	获取本地未处理通知任务	60/min
`POST`	`/api/xhs/notifications/reply`	回复通知	10/min

返回格式

{
  "success": true,
  "data": {}
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "keyword: Required"
  }
}

公开接口（无需鉴权）

方法	路径	说明
`GET`	`/health`	健康检查（运行时长/内存/插件状态）
`GET`	`/sse`	MCP SSE 连接入口
`POST`	`/messages`	MCP JSON-RPC 消息入口

Docker 部署

使用 Compose（推荐）

cd deploy
docker compose up -d

# 查看日志
docker compose logs -f

# 查找 Bearer Token
docker compose logs social-mcp | grep "Bearer Token"

直接运行 Docker

docker build -t social-mcp .

docker run -d \
  --name social-mcp \
  -p 127.0.0.1:3000:3000 \
  --shm-size=1gb \
  --memory=2g \
  --cpus=2.0 \
  --security-opt=no-new-privileges:true \
  --cap-drop=ALL \
  --read-only \
  --tmpfs /tmp:size=512m \
  -v social-mcp-data:/home/appuser/.social-mcp \
  social-mcp

说明：Docker 镜像默认使用 PORT=3000。

环境变量

变量	默认值（本地）	说明
`PORT`	`9527`	HTTP 监听端口
`HOST`	`127.0.0.1`	绑定地址（`0.0.0.0` 需设置 `ALLOW_REMOTE`）
`HEADLESS`	`true`	是否无头运行浏览器
`BROWSER_BIN`	自动探测	自定义 Chromium 路径
`LOG_LEVEL`	`info`	日志级别（`debug`/`info`/`warn`/`error`）
`NODE_ENV`	`development`	运行环境
`COOKIE_DIR`	`~/.social-mcp`	Cookie/Token 存储目录
`MAX_QUEUE_DEPTH`	`10`	单平台最大排队深度
`ALLOW_REMOTE`	空	仅当值为 `yes-i-understand-the-risk` 时允许公网绑定
`XHS_NOTIFICATION_POLL_ENABLED`	`true`	是否启用通知定时同步到 SQLite
`XHS_NOTIFICATION_POLL_INTERVAL_SEC`	`60`	通知同步周期（秒，最小 15）
`XHS_NOTIFICATION_POLL_MAX_COUNT`	`20`	每次同步最多拉取通知数

项目结构

social-mcp/
├── src/
│   ├── index.ts
│   ├── server/
│   │   ├── app.ts
│   │   └── middleware.ts
│   ├── browser/
│   │   └── manager.ts
│   ├── cookie/
│   │   └── store.ts
│   ├── config/
│   │   └── index.ts
│   ├── utils/
│   │   ├── logger.ts
│   │   ├── errors.ts
│   │   └── downloader.ts
│   └── platforms/
│       └── xiaohongshu/
│           ├── index.ts
│           ├── routes.ts
│           ├── schemas.ts
│           ├── selectors.ts
│           ├── login.ts
│           ├── feeds.ts
│           ├── search.ts
│           ├── feed-detail.ts
│           ├── user-profile.ts
│           ├── my-notes.ts
│           ├── publish.ts
│           ├── publish-video.ts
│           ├── comment.ts
│           ├── interaction.ts
│           ├── notification.ts
│           ├── notification-state.ts
│           └── notification-sync.ts
└── web/
    └── src/

License

ISC

8.2 KiB Raw Blame History Unescape Escape

Social MCP