# PigBun RedNote MCP

[![npm](https://img.shields.io/npm/v/@pigbun-ai/pigbun-rednote-mcp)](https://www.npmjs.com/package/@pigbun-ai/pigbun-rednote-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

[English](docs/README.en.md) | 简体中文

基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的小红书研究与学习工具 — 帮助开发者探索 MCP 协议在内容平台场景下的应用。

根据 API Key 配额类型自动切换**单人模式**或**多会话模式**，无需安装不同的包。

## 免责声明

> **本项目为开源技术研究项目，仅供学习 MCP 协议和浏览器自动化技术之用。**
>
> - 本项目与小红书（Xiaohongshu）没有任何关联，非官方产品，未获得任何形式的授权或认可
> - 使用者应自行遵守小红书平台的[用户协议](https://www.xiaohongshu.com/protocols/user)和相关服务条款
> - 本软件按"原样"（AS IS）提供，不提供任何明示或暗示的保证，包括但不限于适销性、特定用途适用性和非侵权性的保证
> - 在任何情况下，作者或版权持有人均不对因使用本软件而产生的任何索赔、损害或其他责任负责
> - 使用者需自行承担使用本工具的全部风险和法律责任
> - 请勿将本工具用于任何违反法律法规或平台规则的用途

## 快速开始

### 1. 获取 API Key

前往 [pigbunai.com](https://pigbunai.com) 注册账号，在 Dashboard 中创建 API Key。

免费配额：每日 50 次调用（登录操作不计次）。

### 2. 安装浏览器（通常自动完成）

首次使用时，MCP Server 会自动检测并安装所需的浏览器。如果自动安装失败，可手动运行：

```bash
npx patchright install chromium
```

### 3. 初始化登录

```bash
npx @pigbun-ai/pigbun-rednote-mcp init
```

浏览器会自动打开，手动完成小红书扫码登录。Cookie 保存在 `~/.mcp/rednote/cookies.json`。

### 4. 配置 MCP 客户端

适用于 Claude Desktop、Cursor、Windsurf、Claude Code 等支持 MCP 的客户端：

```json
{
  "mcpServers": {
    "pigbun-rednote-mcp": {
      "command": "npx",
      "args": ["@pigbun-ai/pigbun-rednote-mcp@latest", "--stdio"],
      "env": {
        "PIGBUN_API_KEY": "pb_live_your_key_here"
      }
    }
  }
}
```

将 `pb_live_your_key_here` 替换为你在 Dashboard 中获取的 API Key。

## 单人模式 vs 多会话模式

同一个包，根据 API Key 配额类型自动切换：

| 功能 | 单人模式 | 多会话模式 |
|------|---------|-----------|
| 会话数量 | 1 个 | 最多 10 个（按配额） |
| 工具数量 | 27 个 | 29 个（多 2 个会话管理工具） |
| accountId 参数 | 无（自动使用唯一会话） | 所有操作工具自动追加 |
| Web 管理面板 | ❌ | ✅ `http://localhost:3001` |
| 登录方式 | 命令行浏览器登录 | Web 管理界面扫码 |
| 会话保活 | ❌ | ✅ 心跳 + 生物节律模拟 |
| 会话健康监控 | ❌ | ✅ 实时检测 + 自动重启 |
| 配额状态监控 | ❌ | ✅ 运行时降级保护 |

## 功能一览

### 搜索与内容

| 工具 | 说明 |
|------|------|
| `search_notes` | 关键词搜索笔记（返回含 xsec_token 的链接） |
| `get_note_content` | 获取笔记详情（标题、正文、图片、视频等） |
| `get_note_comments` | 获取笔记评论列表 |
| `view_image` | 获取图片 Base64（供 AI 查看分析） |

### 发布笔记

| 工具 | 说明 |
|------|------|
| `publish_note` | 发布图文笔记（至少一张图片） |
| `publish_note_video` | 发布视频笔记 |
| `publish_note_text` | 发布纯文字笔记（自动生成封面图） |
| `publish_note_article` | 发布长文笔记（标题无字数限制） |

### 笔记管理

| 工具 | 说明 |
|------|------|
| `get_my_notes` | 获取自己的笔记列表（创作者中心） |
| `edit_note` | 编辑已发布笔记的标题、正文、标签 |
| `delete_note` | 删除已发布的笔记 |

### 评论互动

| 工具 | 说明 |
|------|------|
| `comment_note` | 在笔记下发表一级评论 |
| `reply_comment` | 回复笔记下的指定评论 |

### 社交互动

| 工具 | 说明 |
|------|------|
| `like_note` | 给笔记点赞 |
| `collect_note` | 收藏笔记 |
| `follow_author` | 关注笔记作者 |

### 数据分析

| 工具 | 说明 |
|------|------|
| `get_dashboard_overview` | 创作者数据总览（曝光、观看、互动、涨粉） |
| `get_content_analytics` | 内容分析（每篇笔记的详细数据） |
| `get_fans_analytics` | 粉丝数据（总量、新增/流失、画像、活跃度） |
| `discover_trending` | 发现热门话题（多关键词热度对比） |
| `analyze_best_publish_time` | 分析最佳发布时间 |
| `generate_content_report` | 生成综合运营报告 |
| `get_inspiration_topics` | 获取笔记灵感话题 |
| `get_activity_center` | 获取官方活动列表 |

### 其他

| 工具 | 说明 |
|------|------|
| `login` | 小红书扫码登录 |
| `get_notifications` | 获取通知消息（评论、点赞、关注） |
| `get_share_link` | 获取笔记分享链接 |

### 多会话模式独有

| 工具 | 说明 |
|------|------|
| `list_accounts` | 列出所有已登录会话及其信息 |
| `check_accounts_status` | 批量检查所有会话的登录状态 |

## 发布笔记参数

四种发布模式：

| 模式 | 工具 | 说明 |
|------|------|------|
| 图文 | `publish_note` | 至少一张图片，标题最多 20 字 |
| 视频 | `publish_note_video` | 提供一个视频文件 |
| 纯文字 | `publish_note_text` | 无需图片，自动生成封面 |
| 长文 | `publish_note_article` | 长篇内容，标题无字数限制 |

通用参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `title` | string | ✅ | 标题 |
| `content` | string | ✅ | 正文 |
| `images` | string[] | 仅图文 | 本地图片文件路径 |
| `video` | string | 仅视频 | 本地视频文件路径 |
| `tags` | string[] | ❌ | 话题标签 |
| `keepAlive` | boolean | ❌ | 保持浏览器打开（用于连续操作） |

## 会话保活（多会话模式）

多会话模式内置智能心跳系统，模拟真实浏览行为以维持会话有效性：

- 凌晨 2-7 点有 80% 概率跳过心跳（符合自然作息）
- 白天有 30% 概率跳过某次心跳（模拟间歇性使用）
- 心跳时随机滚动探索页，触发真实的浏览遥测

## 调试

使用 MCP Inspector：

```bash
PIGBUN_API_KEY=pb_live_xxx npx @modelcontextprotocol/inspector npx @pigbun-ai/pigbun-rednote-mcp --stdio
```

## 注意事项

- Cookie 文件包含敏感数据，请妥善保管
- 定期重新登录以刷新 Cookie
- 所有操作从本地 IP 发起，不经过中心化代理
- 请合理使用，遵守平台相关规则

## API 配额

API Key 用于接口调用频率管理和滥用防护：

| 配额 | 会话数 | 说明 |
|------|-------|------|
| 免费 | 1 个 | 每日 50 次调用 |
| 进阶 | 最多 10 个 | [了解更多](https://pigbunai.com) |

前往 [pigbunai.com](https://pigbunai.com) 了解详情。

## License

MIT — 详见 [LICENSE](LICENSE)