xhs-mac-mcp

Original source / Raw SKILL.md

---
name: xhs-mac-mcp
description: 通过 macOS Accessibility API 控制小红书（rednote）App。支持私信、评论回复、视频评论读取、搜索、点赞、收藏、作者数据等。需要 Mac + rednote App 可见 + Terminal 辅助功能权限。
---

# xhs-mac-mcp

通过 OpenClaw Plugin 调用，20 个 `xhs_*` tools 已注册，直接 call 即可。

## 安装

```bash
cd ~/.agents/skills/xhs-mac-mcp && bash install.sh
openclaw config set tools.allow '["xhs-mac"]'
openclaw gateway restart
```

⚠️ 系统设置 → 隐私与安全 → 辅助功能 → 开启 Terminal

## 按需读取的参考文件

| 需要做什么 | 读哪个文件 |
|-----------|-----------|
| 导航、截图、搜索 | `docs/ref-navigation.md` |
| 浏览 Feed、打开笔记 | `docs/ref-feed.md` |
| 点赞、收藏、评论、回复、删除 | `docs/ref-note.md` |
| 私信（发送/打开对话） | `docs/ref-dm.md` |
| 主页数据（关注/粉丝/bio） | `docs/ref-profile.md` |
| 图文帖限制 / 注意事项 | `docs/ref-limits.md` |

## 快速参考

```
xhs_screenshot          截图
xhs_navigate            切底部Tab (home/messages/profile)
xhs_navigate_top        切顶部Tab (follow/discover/video)
xhs_back                返回
xhs_search              搜索
xhs_scroll_feed         滚动Feed
xhs_open_note           打开笔记(col,row)
xhs_like / xhs_collect  点赞 / 收藏
xhs_get_note_url        获取分享链接
xhs_follow_author       关注作者
xhs_open_comments       打开评论区
xhs_scroll_comments     滚动评论
xhs_get_comments        获取评论列表
xhs_post_comment        发评论
xhs_reply_to_comment    回复评论(index,text)
xhs_delete_comment      删评论(index) ⚠️不可逆
xhs_open_dm             打开私信(index)
xhs_send_dm             发私信(text)
xhs_get_author_stats    读主页数据
```


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### docs/ref-navigation.md

```markdown
# 导航 & 截图

## xhs_screenshot
截取当前界面截图。无参数。

## xhs_navigate
切换底部 Tab。
- `tab`: `home`(首页) | `messages`(消息) | `profile`(我)

## xhs_navigate_top
切换顶部 Tab（需在首页）。
- `tab`: `follow`(关注) | `discover`(发现) | `video`(视频)

## xhs_back
返回上一页。无参数。

## xhs_search
搜索关键词，跳转搜索结果页。
- `keyword`: 搜索词（string，必填）

## 使用顺序示例
```
xhs_navigate(tab="home")
→ xhs_navigate_top(tab="discover")
→ xhs_search(keyword="AI论文")
→ xhs_screenshot()  # 确认结果
```

```

### docs/ref-feed.md

```markdown
# Feed 浏览

## xhs_scroll_feed
滚动 Feed 流。
- `direction`: `down`(默认) | `up`
- `times`: 滚动次数（默认 3）

## xhs_open_note
点击 Feed 双列瀑布流中的笔记。
- `col`: 0=左列，1=右列（默认 0）
- `row`: 行号，0=第一行（默认 0）

## 使用顺序示例
```
xhs_navigate(tab="home")
→ xhs_navigate_top(tab="discover")
→ xhs_scroll_feed(direction="down", times=3)  # 刷新内容
→ xhs_open_note(col=0, row=0)  # 打开左列第一篇
→ xhs_screenshot()  # 确认进入笔记详情
```

```

### docs/ref-note.md

```markdown
# 笔记互动（点赞 / 收藏 / 评论 / 私信）

> 所有操作需先用 xhs_open_note 进入笔记详情页。

## 基础互动

### xhs_like
点赞当前笔记。无参数。

### xhs_collect
收藏当前笔记。无参数。

### xhs_get_note_url
获取当前笔记的分享链接（xhslink.com 短链）。无参数。返回 URL 字符串。

### xhs_follow_author
关注当前笔记的作者。无参数。

## 评论区

### xhs_open_comments
打开评论区。
- 视频帖：弹出侧边评论层，完整可用
- 图文帖：只聚焦输入框，评论列表 AX 读不到（见 ref-limits.md）

### xhs_scroll_comments
滚动评论区。
- `times`: 滚动次数（默认 3）
- 视频帖完全可用；图文帖受限

### xhs_get_comments
获取评论列表。无参数。返回：
```json
[{"index": 0, "author": "用户名", "cx": 1450, "cy": 368}, ...]
```
- **视频帖可靠**，图文帖 AX 暴露有限

### xhs_post_comment
发送评论。
- `text`: 评论内容（string，必填）

### xhs_reply_to_comment
回复某条评论。
- `index`: 评论序号（来自 get_comments 的 index 字段）
- `text`: 回复内容（string，必填）

### xhs_delete_comment
删除评论（**只能删自己发的，不可逆**）。
- `index`: 评论序号（来自 get_comments）

## 评论操作标准流程
```
xhs_open_comments()
→ xhs_get_comments()           # 拿到评论列表和 index
→ xhs_reply_to_comment(index=0, text="回复内容")
# 或
→ xhs_delete_comment(index=0)  # 确认是自己的评论再删
```

```

### docs/ref-dm.md

```markdown
# 私信（DM）

> 需先导航到消息页，再打开对话。

## xhs_open_dm
打开消息列表中指定序号的私信对话。
- `index`: 对话序号，0=列表第一条（默认 0）
- 内部自动先 navigate_tab("messages")，无需手动切换

## xhs_send_dm
在当前私信对话中发送消息（需先 xhs_open_dm）。
- `text`: 消息内容（string，必填）

## 标准流程
```
xhs_open_dm(index=0)        # 打开第一条对话
→ xhs_send_dm(text="你好") # 发送消息
→ xhs_screenshot()          # 确认发送成功
```

```

### docs/ref-profile.md

```markdown
# 个人主页 & 作者数据

## xhs_get_author_stats
读取当前主页的统计数据。无参数。
返回：
```json
{
  "following": "2",
  "followers": "29",
  "likes": "302",
  "bio": "OpenClaw驱动的一只小虾\n🦞 本虾每天潜入 ArXiv 深海捞论文"
}
```

**前提**：需先导航到主页（自己或他人）。

## 查看自己主页
```
xhs_navigate(tab="profile")
→ xhs_get_author_stats()
```

## 查看笔记作者主页
```
# 进入笔记详情页后，点作者头像（暂无专用 tool）
# 可截图后用 image tool 读数据作为替代
xhs_screenshot()
```

```

### docs/ref-limits.md

```markdown
# 已知限制（必读）

## 图文帖评论区：AX 硬限制

**现象**：图文帖评论文字完全读不到。
**根因**：小红书图文帖使用自绘渲染（Metal/Canvas），AX API 无法获取文字内容。
- `AXNumberOfCharacters = 0`，`AXValue = kAXErrorNoValue`
- 尝试过：AXValue / AXSelectedText / AXCustomContent / AXVisibleText / AS 全遍历 → 全部空

**视频帖无此限制**：open_comments 弹出侧边层，get_comments 完整返回用户名 + 坐标。

**图文帖替代方案**：`xhs_screenshot()` + image tool 分析截图文字。

## App 可见性要求

- rednote App 必须**在屏幕上可见**（不能最小化）
- 屏幕**不能锁定**（锁屏后鼠标事件全部失效）
- 可以在后台（其他窗口在前面），不需要在最前面
- 长时间运行建议：`caffeinate -di &`

## search() 注意事项

从非首页状态（如笔记详情页）调用 search，App 可能还停在当前页。
标准做法：先 `xhs_navigate(tab="home")`，再 `xhs_navigate_top(tab="discover")`，再 search。

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### README.md

```markdown
# xhs-mac-mcp

通过 macOS Accessibility API 控制小红书（rednote）App 的 OpenClaw Plugin。

## 功能

补充 [xiaohongshu-mcp](https://github.com/...)（headless 版）无法实现的功能：

| 功能 | 说明 |
|------|------|
| 私信（send_dm） | headless 版无法做到 |
| 回复/删除评论 | 需要登录态 + App 交互 |
| 视频评论区完整读取 | AX API 可直接拿到评论列表 |
| 作者主页数据 | 关注/粉丝/获赞/bio |
| 搜索、点赞、收藏、关注 | 全部支持 |

## 前提条件

- Mac 安装了小红书（rednote）App
- Terminal 已获得辅助功能权限：**系统设置 → 隐私与安全 → 辅助功能** → 开启 Terminal
- 使用时 rednote App 必须在屏幕上**可见**（不能最小化/锁屏）
- 建议长时间任务时运行 `caffeinate -di &` 防止息屏

## 安装

```bash
# 1. 安装依赖
cd ~/.agents/skills/xhs-mac-mcp
uv sync   # 或 pip install atomacos pyobjc-framework-Quartz

# 2. 注册为 OpenClaw Plugin
ln -sf ~/.agents/skills/xhs-mac-mcp ~/.openclaw/extensions/xhs-mac

# 3. 允许 plugin 工具（加到 openclaw.json）
openclaw config set tools.allow '["xhs-mac"]'

# 4. 重启 Gateway
openclaw gateway restart
```

验证：
```bash
openclaw plugins list | grep xhs-mac
# 应显示 status: loaded
```

## 可用 Tools

| Tool | 说明 |
|------|------|
| `xhs_screenshot` | 截取当前界面截图 |
| `xhs_navigate` | 切换底部 Tab（home/messages/profile）|
| `xhs_navigate_top` | 切换顶部 Tab（follow/discover/video）|
| `xhs_back` | 返回上一页 |
| `xhs_search` | 搜索关键词 |
| `xhs_scroll_feed` | 滚动 Feed 流 |
| `xhs_open_note` | 打开 Feed 中的笔记 |
| `xhs_like` | 点赞 |
| `xhs_collect` | 收藏 |
| `xhs_get_note_url` | 获取笔记分享链接 |
| `xhs_follow_author` | 关注作者 |
| `xhs_open_comments` | 打开评论区 |
| `xhs_scroll_comments` | 滚动评论区 |
| `xhs_get_comments` | 获取评论列表 |
| `xhs_post_comment` | 发评论 |
| `xhs_reply_to_comment` | 回复评论 |
| `xhs_delete_comment` | 删除评论（只能删自己的）|
| `xhs_open_dm` | 打开私信对话 |
| `xhs_send_dm` | 发送私信 |
| `xhs_get_author_stats` | 读取主页数据 |

## 已知限制

- **图文帖评论**：小红书图文帖使用自绘渲染（Metal/Canvas），AX API 无法读取评论文字。视频帖无此限制，评论完整可读。
- **屏幕锁定**：锁屏后鼠标事件失效，需保持屏幕常亮。
- **App 可见性**：App 最小化后操作失效，需在屏幕上可见（可在后台，不需要在最前面）。

## 同时使用 Claude Desktop / Cursor

本项目同时包含标准 MCP server（`server.py`），可用于 Claude Desktop 或 Cursor：

```json
// claude_desktop_config.json
{
  "mcpServers": {
    "xhs-mac": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/xhs-mac-mcp", "python", "server.py"]
    }
  }
}
```

```

### _meta.json

```json
{
  "owner": "huangrh99",
  "slug": "xhs-mac-mcp",
  "displayName": "小红书 Mac Controller",
  "latest": {
    "version": "1.1.0",
    "publishedAt": 1772300348823,
    "commit": "https://github.com/openclaw/skills/commit/e9d2766159272bc192a571e7d2ea079331e0ece8"
  },
  "history": []
}

```