# @emit/xhs-cover-mcp-server

<p align="center">
  <strong>小红书封面生成器 MCP Server</strong><br>
  让 AI 助手为你生成精美的小红书风格封面图
</p>

<p align="center">
  <a href="#安装">安装</a> •
  <a href="#快速开始">快速开始</a> •
  <a href="#工具说明">工具说明</a> •
  <a href="#配置">配置</a> •
  <a href="#常见问题">常见问题</a>
</p>

---

## 简介

这是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器，让 Claude、Cursor、Windsurf 等 AI 工具能够直接生成小红书风格的封面图片。

**一句话概括：** 告诉 AI 你想要什么文案，它帮你生成一张精美的封面图。

## 安装

### 方式一：npm 全局安装

```bash
npm install -g @emit/xhs-cover-mcp-server
```

### 方式二：npx 直接运行

无需安装，直接使用：

```bash
npx @emit/xhs-cover-mcp-server
```

### 方式三：使用 OpenClaw Skill

如果你是 [OpenClaw](https://openclaw.ai) 用户，可以直接安装我们的 Skill：

```bash
# 在 OpenClaw 中安装
clawhub install xhs-cover
```

详见 [xhs-cover-skill](https://github.com/xwchris/xhs-cover-skill)

## 快速开始

### 1. 获取 API Key

使用前需要获取 API Key：

1. 访问 [xhscover.cn](https://xhscover.cn) 注册账号
2. 在控制台获取你的 API Key
3. 新用户赠送 10 credits（可免费生成 10 张封面）

### 2. 配置 MCP 客户端

#### Claude Desktop

编辑 Claude Desktop 配置文件：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

添加配置：

```json
{
  "mcpServers": {
    "xiaohongshu-cover": {
      "command": "npx",
      "args": ["-y", "@emit/xhs-cover-mcp-server"],
      "env": {
        "XHS_COVER_API_URL": "https://xhs-cover-api.xwchris.workers.dev",
        "XHS_COVER_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### Cursor

在项目根目录创建 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "xiaohongshu-cover": {
      "command": "npx",
      "args": ["-y", "@emit/xhs-cover-mcp-server"],
      "env": {
        "XHS_COVER_API_URL": "https://xhs-cover-api.xwchris.workers.dev",
        "XHS_COVER_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### Windsurf

编辑 Windsurf 配置文件：

- **macOS**: `~/Library/Application Support/Windsurf/windsurf_config.json`
- **Windows**: `%APPDATA%\Windsurf\windsurf_config.json`

配置同 Claude Desktop。

### 3. 开始使用

重启你的 AI 工具后，直接对话即可：

```
你：帮我生成一张小红书封面，文案是"5个习惯让你越来越自律"

Claude：我来帮你生成这张封面...
✅ 封面生成成功！

图片 URL: https://...
消耗 credit: 1
```

## 工具说明

这个 MCP Server 提供三个工具：

### `xhs_generate_cover` - 生成封面

生成小红书风格的封面图片。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `text` | string | ✅ | 封面文案内容 |
| `aspectRatio` | string | ❌ | 宽高比，默认 `3:4` |

**支持的宽高比：**

- `3:4` — 小红书标准竖版（推荐）
- `9:16` — 竖版故事/Reels
- `1:1` — 正方形
- `4:3` — 横版
- `16:9` — 宽屏
- `2:3` — 竖版
- `4:5` / `5:4` — 其他比例

**示例：**

```
生成一张封面：文案"今日份好心情"，比例 1:1
```

### `xhs_get_credits` - 查询余额

查看当前账户的 credit 余额和使用情况。

**参数：** 无

**示例：**

```
帮我查一下封面生成的 credit 余额
```

### `xhs_get_history` - 查看历史

获取最近的封面生成记录。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `limit` | number | ❌ | 返回记录数，默认 10 |

**示例：**

```
帮我看看最近生成了哪些封面
```

## 配置

### 环境变量

| 变量名 | 必填 | 说明 |
|--------|------|------|
| `XHS_COVER_API_URL` | ✅ | API 服务地址 |
| `XHS_COVER_API_KEY` | ✅ | 你的 API Key |

> **提示：** 也支持 `XHS_API_URL` 和 `XHS_API_KEY` 作为别名。

### 本地开发

如果你想在本地运行 API 服务，可以参考 [xhs-cover-skill](https://github.com/xwchris/xhs-cover-skill) 中的说明。

## 常见问题

### Q: 生成的图片文字不清晰怎么办？

AI 图片生成的文字渲染有时不稳定，建议：
1. 尝试重新生成
2. 缩短文案长度
3. 使用更常见的字体风格

### Q: 支持自定义风格吗？

当前版本统一使用小红书清新风格。后续版本会支持：
- 风格模板选择
- 参考图片上传
- 批量生成

### Q: Credits 会过期吗？

不会！购买的 Credits 永久有效，用完为止。

### Q: 如何获取更多 Credits？

访问 [xhscover.cn](https://xhscover.cn) 控制台进行充值，支持多种套餐：

| 套餐 | Credits | 价格 | 单价 |
|------|---------|------|------|
| 体验包 | 100 | ¥6 | ¥0.06/张 |
| 基础包 | 500 | ¥28 | ¥0.056/张 |
| 标准包 | 1000 | ¥48 | ¥0.048/张 |
| 大礼包 | 2000 | ¥88 | ¥0.044/张 |

### Q: 支持哪些 AI 工具？

理论上支持所有 MCP 协议的工具，已测试：
- ✅ Claude Desktop
- ✅ Cursor
- ✅ Windsurf
- ✅ Continue
- ✅ OpenClaw

### Q: 可以在代码中直接调用吗？

可以！使用我们的 REST API 或客户端 SDK：

```bash
# REST API
curl -X POST https://xhs-cover-api.xwchris.workers.dev/api/v1/generate \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "你的文案"}'
```

详见 [xhs-cover-skill](https://github.com/xwchris/xhs-cover-skill) 文档。

## 技术细节

### 系统要求

- Node.js >= 18.0.0
- npm 或 npx

### 依赖

- `@modelcontextprotocol/sdk` — MCP 协议实现
- `@supabase/supabase-js` — 数据库客户端

### 架构

```
MCP Client (Claude/Cursor)
        ↓
    MCP Server (本包)
        ↓
    REST API (Cloudflare Workers)
        ↓
    Gemini AI Model
        ↓
    图片存储 (Cloudflare R2)
```

## 相关链接

- 🌐 网站: [xhscover.cn](https://xhscover.cn)
- 🔌 OpenClaw Skill: [xhs-cover-skill](https://github.com/xwchris/xhs-cover-skill)
- 💬 社区: [Discord](https://discord.com/invite/clawd)

## License

MIT © 2026

---

<p align="center">
  用 AI 解放你的创意 🎨
</p>