# 🚀 小红书 MCP Server — 轻量版

**一个文件。四个工具。让你的 AI 直接发小红书。**

[![Python](https://img.shields.io/badge/Python-3.11+-blue)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-1.0-green)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)
[![Stars](https://img.shields.io/github/stars/luyike221/xhs-mcp-light?style=social)](https://github.com/luyike221/xhs-mcp-light)

> **中文 MCP 生态最轻量的小红书发布工具** — 200 行代码，不依赖重型框架，Claude / Cursor / Copilot 直接操控小红书。

---

## 这是什么

一个 **单文件**（server.py）的 Model Context Protocol (MCP) Server，让你的 AI 助手直接发小红书：

- ✅ 扫码一次，长期免登（Chrome profile 持久化）
- ✅ 发布图文笔记：标题 + 正文 + 多图（最多 9 张）+ 话题标签
- ✅ 搜索笔记
- ✅ 检查登录状态

**竞品对比**：

| | xhs-mcp-light (本项目) | luyike221/xiaohongshu-mcp-python |
|---|---|---|
| 文件数 | **1** | ~10,000 |
| 子项目 | **0** | 6 |
| 核心依赖 | **4** | 30+ |
| 安装到跑通 | **3 分钟** | 30 分钟+ |
| MCP 传输 | **stdio**（Claude Code 原生） | HTTP（需额外起服务） |

---

## 5 分钟上手

### 1. 安装

```bash
# 安装 uv（如果没有）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 克隆项目
git clone https://github.com/luyike221/xhs-mcp-light.git
cd xhs-mcp-light

# 安装依赖（3 个包）
uv sync

# 安装 Chromium 浏览器（首次，约 150MB）
uv run playwright install chromium
```

### 2. 接入 Claude Code

在 Claude Code 设置文件（`~/.claude/settings.json`）中添加：

```json
{
  "mcpServers": {
    "xhs-publisher": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "D:/Claudecoda学习/xhs-mcp-light"
    }
  }
}
```

> 其他 AI 工具（Cursor、Copilot、Codex）的配置见 [MCP 官方文档](https://modelcontextprotocol.io)。

### 3. 扫码登录

重启 Claude Code，然后说：

> "帮我登录小红书"

Claude 会调用 `xhs_login` → 弹出浏览器窗口 → 用小红书 App 扫码 → 完成。一次扫码，永久有效。

### 4. 发布第一篇笔记

> "帮我发一篇小红书：标题'我的 AI 帮我发了这篇笔记'，内容写……，图片用桌面上的 test.jpg"

---

## 四个工具

| 工具 | 说明 | 必填参数 |
|------|------|----------|
| `xhs_login` | 打开浏览器扫码登录 | 无 |
| `xhs_check_login` | 检查登录状态 | 无 |
| `xhs_publish_note` | 发布图文笔记 | `title`, `content`, `images` |
| `xhs_search_feeds` | 搜索笔记 | `keyword` |

---

## 使用示例

### 自然语言（推荐）

> "发一篇小红书：标题'成都周末探店'，正文分享一家藏在巷子里的咖啡馆，图片用桌面的 cafe1.jpg、cafe2.jpg，标签加 成都探店、咖啡馆、周末去哪"

Claude 自动翻译成工具调用，完成发布。

### 直接调用

```python
xhs_publish_note(
  title="成都周末探店",
  content="藏在巷子里的惊喜...",
  images=["C:/Users/xxx/Desktop/cafe1.jpg", "C:/Users/xxx/Desktop/cafe2.jpg"],
  tags=["成都探店", "咖啡馆", "周末去哪"]
)
```

---

## 原理

```
Claude Code ──MCP stdio──▶ server.py ──Playwright──▶ Chrome ──▶ 小红书网页版
                                                          │
                                                    登录态保存在
                                                    xhs-browser-data/
```

- **不碰小红书 API**（不逆向、不抓包）——模拟真人操作浏览器
- **Playwright persistent context** 保存 Chrome profile——一次扫码，长期免登
- **stdio 传输**——不需要起 HTTP 服务，Claude Code 直接启动子进程

---

## 文件结构

```
xhs-mcp-light/
├── server.py          # 全部代码（233 行）
├── pyproject.toml     # 依赖声明
├── .env.example       # 配置模板
├── xhs-browser-data/  # Chrome profile（自动生成，含登录态）
├── assets/            # 图片资源
└── README.md
```

---

## 常见问题

**Q: 会被封号吗？**
A: 本项目模拟真人浏览器操作（有 UI 交互、有随机延迟），发布频率正常就不会。**禁止用于批量灌水、刷量、违规营销**。

**Q: 支持视频吗？**
A: V1.0 图文优先。视频、定时发布、草稿箱管理在 Roadmap 中。

**Q: Windows 图片路径怎么写？**
A: 用正斜杠：`"C:/Users/xxx/Pictures/a.jpg"`，或双反斜杠。**不要用单反斜杠**（JSON 会把它当转义符）。

**Q: Mac / Linux 能用吗？**
A: 可以。安装方式一致，路径用 Unix 格式即可。

**Q: 一个账号能发多少？**
A: 小红书日发上限约 10-15 篇。正常使用不受影响。

---

## Roadmap

- [ ] 视频发布
- [ ] 定时发布
- [ ] 草稿箱管理
- [ ] 数据看板（阅读/点赞/评论）
- [ ] 多账号管理

---

## 赞助

如果这个项目对你有用，请我喝杯咖啡 ☕

<div align="center">
<table>
  <tr>
    <td align="center"><b>微信赞赏</b></td>
    <td align="center"><b>支付宝</b></td>
  </tr>
  <tr>
    <td><img src="assets/wechat-pay.jpg" width="200" alt="微信赞赏码"></td>
    <td><img src="assets/alipay.jpg" width="200" alt="支付宝收款码"></td>
  </tr>
</table>
</div>

---

## 商业合作

**企业批量发布 · 多平台适配（小红书/抖音/闲鱼/公众号）· 私有化部署 · 定制开发**

📧 微信：见赞助码备注 | 📧 Email：portelamicheli636@gmail.com

> 已有客户案例：跨境电商批量种草、MCN 机构多账号分发、个人博主自动化运营。欢迎咨询。

---

## Star 历史

如果这个项目对你有帮助，点个 ⭐ Star 让更多人看到。每个 Star 都是对中文 MCP 生态的一票。

---

**Made with ❤️ by MangoOS × 第三自习室 · 2026**