# Qwen-Image MCP Server

[中文文档](README-zh.md)

An MCP Server for Alibaba Cloud DashScope (Bailian) **Qwen-Image (千问文生图)** models, supporting both **synchronous** and **asynchronous** image generation. Defaults to sync mode (`generate_image_sync`) for the simplest one-shot workflow.

## Gallery

The following images were generated using the [ian-xiaohei-illustrations](https://github.com/helloianneo/ian-xiaohei-illustrations/tree/main) Skills combined with this MCP Server (Qwen text-to-image):

<p align="center">
  <img src="images/qwen-image-2026-07-20T08-32-04-750Z-1.png" width="45%" />
  <img src="images/qwen-image-2026-07-20T08-32-04-841Z-1.png" width="45%" />
</p>

## Features

### Tools

| Tool | Description | Supported Models |
|------|-------------|------------------|
| `generate_image_sync` | Qwen text-to-image - Sync generation (one request, direct result, default mode) ✅ Recommended | qwen-image-2.0-pro, qwen-image-2.0, qwen-image-max |
| `generate_image_async` | Qwen text-to-image - Async generation (submit task, returns task_id, poll for result) | qwen-image-plus, qwen-image |
| `check_task_status` | Check async task status (use with generate_image_async) | - |
| `download_image` | Download generated images locally (call after task completes) | - |

### Supported Models

| Model | Mode | Resolution | Features |
|-------|------|-----------|----------|
| `qwen-image-2.0-pro` | Sync | 512×512 ~ 2048×2048 | Best text rendering & realism |
| `qwen-image-2.0` | Sync | Same as above | Balanced speed & quality |
| `qwen-image-max` | Sync | Fixed options | High realism, low AI artifacts |
| `qwen-image-plus` | Async | Fixed options | Diverse artistic styles |
| `qwen-image` | Async | Fixed options | Basic version |

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DASHSCOPE_API_KEY` | `example-key` | **Required**. Alibaba Cloud DashScope API Key |
| `DASHSCOPE_BASE_URL` | `https://dashscope.aliyuncs.com/api/v1` | API base URL |
| `SYNC_MODEL` | `qwen-image-2.0-pro` | Model for sync generation |
| `ASYNC_MODEL` | `qwen-image-plus` | Model for async generation |
| `SAVE_DIR` | `~/Desktop/qwen-images` | Image save directory. ⚠️ For Amazon Q Desktop: you must add this path in Settings → My computer → Local folders, otherwise the sandbox has no permission to read/write |
| `WORK_DIR` | `process.cwd()` | Working directory |

## Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Build

```bash
npm run build
```

### 3. Configure MCP Client

Add configuration in your MCP client (Claude Desktop, Kiro, etc.):

```json
{
  "mcpServers": {
    "qwen-image": {
      "command": "node",
      "args": ["/path/to/qwen-image-mcp/build/index.js"],
      "env": {
        "DASHSCOPE_API_KEY": "sk-your-api-key",
        "DASHSCOPE_BASE_URL": "https://your-workspace.cn-beijing.maas.aliyuncs.com/api/v1",
        "SYNC_MODEL": "qwen-image-2.0-pro",
        "SAVE_DIR": "/Users/yourname/Pictures/qwen-images"
      }
    }
  }
}
```

## Usage Examples

### Sync Generation (Recommended)

Call `generate_image_sync`:
- prompt: "A ginger cat napping in the sunshine"
- size: "2048*2048"
- prompt_extend: true

Returns image URL directly and auto-downloads to local disk.

### Async Generation

1. Call `generate_image_async` to get `task_id`
2. Poll `check_task_status` every 10 seconds
3. Once completed, call `download_image` to save images

## API Reference

### Sync Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | ✅ | Image prompt |
| negative_prompt | string | - | Negative prompt |
| size | string | - | Resolution, default 2048*2048 |
| n | number | - | Number of images (1-6), default 1 |
| seed | number | - | Random seed |
| prompt_extend | boolean | - | Smart rewriting, default true |
| watermark | boolean | - | Watermark, default false |
| model | string | - | Model name |

### Async Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | ✅ | Image prompt |
| negative_prompt | string | - | Negative prompt |
| size | string | - | Resolution, default 1664*928 |
| seed | number | - | Random seed |
| prompt_extend | boolean | - | Smart rewriting, default true |
| watermark | boolean | - | Watermark, default false |
| model | string | - | Model name |

## Debugging

```bash
npm run inspector
```

## Notes

- Image URLs expire after 24 hours; download promptly
- qwen-image-2.0 series supports **sync mode only**
- qwen-image-plus / qwen-image supports **async mode only**
- **Amazon Q Desktop users**: Q Desktop runs MCP Servers in a sandboxed environment with no default filesystem access. You must configure `SAVE_DIR` as an allowed path in Settings → My computer → Local folders before images can be saved

## License

MIT