XHS-MCP

# MCP 使用指南

本项目已实现完整的 MCP (Model Context Protocol) 服务器，可以通过 Claude Desktop、Cursor 或其他支持 MCP 的客户端使用。

## 🚀 一键部署（推荐）

最简单的方式是使用自动配置脚本，**无需手动配置路径**：

```bash
xhs setup-mcp
```

脚本会自动多个MCP配置选项：



## 前置要求


# MCP 使用指南

本项目包含一个 MCP（Model Context Protocol）服务器，可与 Claude Desktop、Cursor 等支持 MCP 的客户端集成。

下面说明了项目内置的自动配置脚本如何工作，以及手动配置要点。

## 🚀 自动配置（推荐）

项目提供了一个自动配置脚本，用来把本仓库构建输出注册到 Claude Desktop / Cursor 的本地配置中。

运行方式说明：

- 对于已通过 npm 全局安装（或使用 npx）的最终用户：请直接使用 CLI 命令运行（这是推荐的用户用法）：

```bash
# 在终端中运行（全局安装或 npx）
xhs setup-mcp [--claude|--cursor|--all]
```

- 对于在源码树中开发或调试的贡献者，可以在仓库根目录运行（使用 tsx）：

```bash
npm run setup
```

脚本会：
- 检查并在必要时自动运行 `npm run build`，确保 `dist/mcp/index.js`（或兼容的 `dist/index.js`）存在；
- 将 `mcpServers.xhs-mcp` 条目写入目标客户端的配置文件，命令为 `node`，参数为构建输出的绝对路径（例如 `.../dist/mcp/index.js`）；
- 会合并已有配置（不会覆盖其他条目），并在需要时创建父目录。

脚本支持命令行参数来跳过交互式选择：

- `--claude`：只配置 Claude Desktop
- `--cursor`：只配置 Cursor
- `--all`：同时配置 Claude Desktop 和 Cursor

或者（示例）：

- 供最终用户（全局安装或 npx）：

```bash
xhs setup-mcp --claude
```

- 供在源码树中运行的开发者：

```bash
npm run setup -- --claude
```

(注意：通过 `npm run setup` 传递参数时需在 `npm run` 后加 `--`）
或者：

```bash
npm run setup -- --claude
```

（注意：通过 `npm run setup` 传递参数时需在 `npm run` 后加 `--`）

## 前置要求

1. Node.js >= 18
2. 项目已安装依赖（例如：`npm install`）
3. 如果尚未构建，脚本会尝试运行 `npm run build`，但你也可以手动先运行一次 `npm run build`。

建议先运行：

```bash
npm install
npm run build
```

## 脚本会修改的配置文件位置

- Claude Desktop：
  - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
  - Linux: `~/.config/Claude/claude_desktop_config.json`
- Cursor：
  - 所有平台: `~/.cursor/mcp.json`

脚本会把如下条目写入 `mcpServers` 下：

```json
{
  "xhs-mcp": {
    "command": "node",
    "args": ["/absolute/path/to/your/repo/dist/mcp/index.js"]
  }
}
```

脚本会尽量保留和合并已有配置，不会删除其他服务器定义。

## 手动配置（可选）

如果自动脚本无法使用，你可以手动将上面的 `mcpServers.xhs-mcp` 条目加入到对应的配置文件中（确保 `args` 中使用构建产物 `dist/mcp/index.js` 的绝对路径）。

Windows 路径在 JSON 中可以使用双反斜杠 `\\` 或正斜杠 `/`。

## 配置完成后的操作

- 配置完成后请重启对应的客户端使配置生效：
  - Claude Desktop：重启应用
  - Cursor：重启应用，并在 Cursor 中打开 AI 面板（Cmd/Ctrl + L）以确认连接
- 如果 MCP 工具提示未登录，请先在终端运行：

```bash
# 使用 CLI 登录（会打开浏览器让你完成登录）
xhs login
```

## 可用工具（示例）

MCP 配置成功后，服务器会暴露一组工具（名称请以 `src/mcp/index.ts` 中注册的工具为准），常见的工具包括：

- `xhs_login` — 登录小红书（会在浏览器中触发登录流程）
- `xhs_check_login` — 检查登录状态
- `xhs_get_recent_notes` — 获取近期笔记列表
- `xhs_get_operation_data` — 获取运营数据
- `xhs_get_note_detail` — 按 ID 获取笔记详情
- `xhs_read_posting_guidelines` — 读取发帖指南
- `xhs_create_or_update_post` — 创建或更新发帖队列中的帖子
- `xhs_generate_cover` — 生成封面图片

（准确的工具名和参数请参照 `src/mcp/index.ts` 与 `src/mcp/handlers.ts`）