qwen-image-mcp
by yingcaihuang
README.md
# 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
TDQS
A3.8/5.0
Scored across 4 tools
Disambiguation5/5
Each tool serves a unique, clearly distinct purpose: synchronous generation, async submission, status checking, and download. No functional overlap exists.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern (generate_image_*, check_task_status, download_image), making them predictable and easy to understand.
Tool Count5/5
Four tools perfectly cover the core image generation workflow (sync, async, polling, download) without excess or deficiency.
Completeness4/5
Core generation workflow is fully covered (sync, async, status, download). Minor gaps like task cancellation or listing are absent but not critical for basic usage.
Maintenance
ActivityInactive
ResponsivenessNo recent community issues