Qwen-Image MCP Server

中文文档

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 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

npm install

2. Build

npm run build

3. Configure MCP Client

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

{
  "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

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