# Qwen Image 3.0 MCP Server

[![PyPI](https://img.shields.io/pypi/v/qwen-image-mcp?label=PyPI)](https://pypi.org/project/qwen-image-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/qwen-image-mcp)](https://pypi.org/project/qwen-image-mcp/)
[![License](https://img.shields.io/pypi/l/qwen-image-mcp)](https://github.com/wchiway/qwen-image-mcp/blob/master/LICENSE)

基于[阿里云百炼 DashScope API](https://bailian.console.aliyun.com/) 的千问图像生成与编辑 MCP 服务，提供文生图（T2I）和图生图/图像编辑（I2I）能力。

## 功能

| 工具 | 功能 | 说明 |
|------|------|------|
| `generate_image` | 文生图（T2I） | 根据文本提示词直接生成图像 |
| `edit_image` | 图生图/图像编辑（I2I） | 基于 1-3 张参考图结合编辑指令进行精确编辑 |

### 模型选择

| 模型 | 特点 |
|------|------|
| `qwen-image-3.0-pro` | 高质量，适合精细创作 |
| `qwen-image-3.0` | 兼顾质量与速度，适合快速生成 |

## 前提条件

1. **阿里云百炼 API Key** — [获取地址](https://help.aliyun.com/zh/model-studio/get-api-key)
2. **Python >= 3.10**
3. **uv**（推荐）— [安装指引](https://docs.astral.sh/uv/getting-started/installation/)

## 安装

### uvx（无需安装，直接运行）

```bash
uvx qwen-image-mcp
```

### pip

```bash
pip install qwen-image-mcp
```

### 本地开发

```bash
git clone https://github.com/wchiway/qwen-image-mcp
cd qwen-image-mcp
uv sync
```

## 配置

通过环境变量配置 API Key：

```bash
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxx"
```

或创建 `.env` 文件：

```env
# 必填：阿里云百炼 API Key
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxx

# 可选：业务空间 ID（推荐，性能更优）
WORKSPACE_ID=

# 可选：地域（默认 cn-beijing）
REGION=cn-beijing
```

## 使用方式

### MCP 客户端配置（推荐）

在 Claude Code 的 `settings.json` 中添加：

```json
{
  "mcpServers": {
    "qwen-image": {
      "command": "uvx",
      "args": ["qwen-image-mcp"],
      "env": {
        "DASHSCOPE_API_KEY": "sk-你的key",
        "WORKSPACE_ID": "",
        "REGION": "cn-beijing"
      }
    }
  }
}
```

### uvx 直接运行

```bash
uvx qwen-image-mcp
```

### 本地安装运行

```bash
qwen-image-mcp
```

## 工具参考

### generate_image — 文生图

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:--:|--------|------|
| `prompt` | string | ✅ | — | 正向提示词，描述图像内容、风格和构图，支持中英文 |
| `model` | string | — | `qwen-image-3.0-pro` | 模型名称 |
| `size` | string | — | 自动推荐 | 输出分辨率，格式 `宽*高`，如 `1024*1024` |
| `n` | integer | — | 1 | 生成数量（1-6） |
| `prompt_extend` | boolean | — | true | 提示词智能改写 |
| `prompt_extend_mode` | string | — | direct | 改写方式：`direct` / `agent` |
| `negative_prompt` | string | — | — | 反向提示词 |
| `seed` | integer | — | — | 随机种子（0-2147483647） |
| `watermark` | boolean | — | false | 是否添加水印 |

### edit_image — 图生图/图像编辑

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|:--:|--------|------|
| `prompt` | string | ✅ | — | 编辑指令，描述期望的编辑效果，支持中英文 |
| `images` | string[] | ✅ | — | 参考图像列表（1-3 张），URL 或 Base64 |
| `model` | string | — | `qwen-image-3.0-pro` | 模型名称 |
| `size` | string | — | 自动推荐 | 输出分辨率，格式 `宽*高` |
| `n` | integer | — | 1 | 生成数量（1-6） |
| `prompt_extend` | boolean | — | true | 提示词智能改写 |
| `prompt_extend_mode` | string | — | direct | 仅支持 `direct`（I2I 限制） |
| `negative_prompt` | string | — | — | 反向提示词 |
| `seed` | integer | — | — | 随机种子（0-2147483647） |
| `watermark` | boolean | — | false | 是否添加水印 |

### 图像输入格式

- **公网 URL**：`https://example.com/image.png`
- **Base64 编码**：`data:image/png;base64,iVBORw0KGgo...`
- 支持格式：JPG、JPEG、PNG、BMP、TIFF、WEBP、GIF
- 单张不超过 10MB，分辨率建议 384-2048 像素

## 环境变量

| 变量 | 必填 | 默认值 | 说明 |
|------|:--:|--------|------|
| `DASHSCOPE_API_KEY` | ✅ | — | 阿里云百炼 API Key |
| `WORKSPACE_ID` | — | — | 业务空间 ID，不设则使用旧域名 |
| `REGION` | — | `cn-beijing` | 地域：`cn-beijing` / `ap-southeast-1` |
| `IMAGE_GEN_TIMEOUT` | — | `120` | API 请求超时（秒） |
| `LOG_LEVEL` | — | `INFO` | 日志级别：`DEBUG` / `INFO` / `WARNING` |

## 示例

### 文生图 — 生成一张风景照

```
prompt: "一幅秋日山间晨雾的风景摄影，暖金色阳光穿透薄雾，远山层叠，前景有金黄色的落叶松林"
```

### 图生图 — 人物换装

```
images: ["https://example.com/portrait.jpg"]
prompt: "保留人物面部特征，将服装换为深蓝色商务西装，背景改为现代办公室"
```

### 图生图 — 风格转换

```
images: ["https://example.com/photo.jpg"]
prompt: "将这张照片转换为宫崎骏动画风格，保持构图不变"
```

## 响应格式

成功返回的图像 URL 有效期为 **24 小时**，请及时下载保存。

```
✅ 文生图完成

**图像 1**
- URL（24h 有效）: https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png

分辨率: 1024×1024
生成数量: 1
输入图片数: 0
request_id: 571ae02f-5c9d-436c-83c2-f221e6df0xxx
```

## 技术栈

- Python 3.10+
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 2.0+
- [httpx](https://www.python-httpx.org/)
- [uv](https://docs.astral.sh/uv/) — 包管理与构建

## 许可证

MIT