# jimeng-volcengine-mcp

即梦AI MCP服务器 - 火山引擎官方API版。为Claude Code提供强大的AI图像生成能力，使用火山引擎v3 API直接调用即梦AI (Doubao Seedream 4.0)。

## 功能特性

- ✨ 文生图：根据文字描述生成图片
- 🎨 图生图：基于参考图片生成新图片
- 🖼️ 批量生成：支持多个prompt批量生成
- 📚 组图生成：自动生成一组相关图片（最多15张）
- 💾 自动保存：生成的图片自动下载到本地
- 🎯 多种尺寸：支持1:1、16:9、9:16等8种比例
- ⚡ 高分辨率：最高支持4K分辨率输出

## 安装

### NPM安装（推荐）

```bash
npm install -g jimeng-volcengine-mcp
```

### 源码安装

```bash
git clone https://github.com/chengfeng/jimeng-volcengine-mcp.git
cd jimeng-volcengine-mcp
npm install
```

## 配置

### 1. 获取API密钥

在 [火山引擎控制台](https://console.volcengine.com) 注册并获取API密钥。

### 2. 配置Claude Code

#### NPM安装后配置

```bash
claude mcp add-json jimeng-volcengine '{
  "command": "npx",
  "args": ["jimeng-volcengine-mcp"],
  "env": {
    "ARK_API_KEY": "你的API密钥",
    "JIMENG_OUTPUT_DIR": "/path/to/save/images"
  }
}'
```

#### 源码安装后配置

```bash
claude mcp add-json jimeng-volcengine '{
  "command": "node",
  "args": ["/path/to/jimeng-volcengine-mcp/index.js"],
  "env": {
    "ARK_API_KEY": "你的API密钥",
    "JIMENG_OUTPUT_DIR": "/path/to/save/images"
  }
}'
```

### 3. 环境变量说明

- `ARK_API_KEY`: 火山引擎API密钥（必需）
- `JIMENG_OUTPUT_DIR`: 图像保存目录（可选，默认为当前目录下的jimeng_volc_images）

## 使用示例

### 基础用法

```javascript
// 文生图
jimeng("一只可爱的猫咪")

// 图生图
jimeng("改为夜晚风格", {image: "http://example.com/image.jpg"})

// 批量生成多个不同的图片
jimeng(["猫", "狗", "兔子"])
```

### 组图生成（特色功能）

```javascript
// 自动判断生成组图数量
jimeng("生成3张不同时间段的城市风景：早晨、中午、夜晚", {
  sequential: "auto",
  max_images: 3
})

// 生成一组不同角度的产品图
jimeng("生成5张不同角度的手表产品图", {
  sequential: "auto",
  max_images: 5
})
```

## 参数说明

| 参数 | 类型 | 说明 | 默认值 |
|-----|------|------|--------|
| prompt | string/array | 描述文本（必需） | - |
| image | string/array | 参考图片URL | null |
| size | string | 图片尺寸比例 | "1:1" |
| watermark | boolean | 是否添加水印 | false |
| sequential | string | 组图生成模式（"auto"/"disabled"） | "disabled" |
| max_images | number | 组图最大数量（1-15） | 15 |
| stream | boolean | 是否流式传输 | false |

### 支持的尺寸

- 1:1 (2048x2048)
- 4:3 (2304x1728)
- 3:4 (1728x2304)
- 16:9 (2560x1440)
- 9:16 (1440x2560)
- 3:2 (2496x1664)
- 2:3 (1664x2496)
- 21:9 (3024x1296)

## 注意事项

1. 需要在火山引擎控制台开通 doubao-seedream-4-0-250828 模型
2. 组图生成时，参考图数量 + 生成图数量不能超过15张
3. 生成高分辨率或多张图片时需要更长时间
4. 图片会自动保存到指定目录，便于后续使用

## License

MIT