# 📕 xhs-mcp — 把小某书变成你的 MCP 工具

> **本机运行 · Chrome 驱动 · 小号安全** — 小红书 ⇌ 任意 MCP 宿主（优先 DSH）

一个轻量 **MCP Server**，让你在 DSH / Claude / Cursor 等宿主里通过**私聊/工具调用操作小红书：
**登录、搜索笔记！（发帖能力预留，需主人明确授权）

---

## ✨ 功能

| 能力 | 说明 | 状态 |
|---|---|---|
| 🔐 **独立登录态** | 独立 Chrome profile，扫码一次永久免登录 | ✅ |
| 🔍 **搜索笔记** | 关键词搜索，返回标题 + 链接 | ✅ |
| 🛡️ **反检测** | 真 Chrome + 真实 UA + 移除 webdriver 标记 | ✅ |
| 👤 **小号隔离** | profile 独立，不碰主人日常账号 | ✅ |
| 📝 **发帖** | 接口预留（需主人明确授权） | 🚧 |
| 🖥️ **多宿主** | stdio MCP，DSH/Claude/Cursor 通吃 | ✅ |

---

## 🚀 快速开始（DSH 优先）

### 前置
- **Node.js ≥ 20**
- **Google Chrome 已装）（或指定路径）

### 1️⃣ 下载

```bash
git clone https://github.com/HUliangwei/xhs-mcp.git
cd xhs-mcp
npm install          # 安装 playwright-core
```

### 2️⃣ 配置

```bash
cp .env.example .env
# 按需改 XHS_PROFILE（多账号用不同名）
```

### 3️⃣ 注册到 DSH
把 dsh-bundle/ 复制进你的 profile bundles，并在 profile 的 package.json dsh.profile.bundles 加上 ./bundles/xhs-mcp：
```json
{ "dsh": { "profile": { "bundles": [ "./bundles/xhs-mcp" ] } } }
```
重启 DSH → 工具组 xhs_* 可用。

### 4️⃣ 其他宿主
```json
{ "mcpServers": { "xhs": { "command": "node", "args": ["<路径>/xhs-mcp-server.mjs"] } } }
```

---

## 🛠️ 工具

| 工具 | 说明 |
|---|---|
| xhs_login | 打开真实 Chrome，扫码登录（180s，持久化） |
| xhs_search | 搜笔记：{ keyword, count } → 标题+链接 |
| xhs_status | 登录状态检查 |

---

## 🛡️ 安全设计

- **仅私聊/工具调用：不接入任何群聊广播
- **小号专用：独立 profile，登录态隔离，不碰主人主账号
- **只读优先：当前只读+搜索；发帖需主人明确授权、低频合规
- **本地运行：无远程服务器，数据不出本机
- **不进 git：profiles/（登录态）、.env 全忽略

---

## 📜 开源

Apache-2.0 · GitHub

**觉得好用？⭐ Star！！