How do I use qwen-image-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@qwen-image-mcp generate an image of a serene mountain lake at sunset" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

qwen-image-mcp

by yingcaihuang

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

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

Related MCP server: Seedream 4.0 MCP Server

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

Call generate_image_async to get task_id
Poll check_task_status every 10 seconds
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

Available Tools

4 tools

check_task_statusA

Check async image generation task status.

ParametersJSON Schema

Name	Required	Description	Default
`task_id`	Yes	Task ID from generate_image_async.

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility. It only states 'check status' without detailing possible status values (e.g., pending, completed, failed), whether the call is idempotent, or any rate limits. This is minimal transparency for a polling tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no extraneous information. While it could include more detail without sacrificing conciseness, it is well-structured and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description does not explain the format or possible values of the status response. For a check-status tool, an agent likely needs to know what the returned status looks like (e.g., string enum) to decide next actions. The description is incomplete in this regard.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'task_id' has a schema description specifying it comes from 'generate_image_async,' which adds valuable context beyond the type and requirement. With 100% schema coverage, the description provides meaningful additional guidance on where the ID originates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Check async image generation task status,' specifying the verb (check), resource (async image generation task), and the operation (status). This distinguishes it from sibling tools like generate_image_sync, generate_image_async, and download_image, which focus on creation or downloading.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage after calling generate_image_async, but it does not provide explicit guidance on when to use this tool versus alternatives, nor does it mention polling behavior or that it should be called repeatedly until completion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

download_imageB

Download images from a completed async task.

ParametersJSON Schema

Name	Required	Description	Default
`task_id`	Yes	Task ID from async generation.
`save_path`	No	Custom save directory (absolute path). Default: SAVE_DIR.

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only states 'Download images from a completed async task' without disclosing what happens if the task is incomplete, any side effects, or the output format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no unnecessary words. It is front-loaded with the key action and resource.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the description lacks completeness. It does not mention that the task must be completed, how to obtain the task_id, or that save_path is optional.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no parameter meaning beyond what the schema provides, but the schema itself is descriptive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Download' and the resource 'images from a completed async task.' It effectively distinguishes from sibling tools like generate_image_sync, generate_image_async, and check_task_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives. It implies use after async task completion but does not mention prerequisites like checking task status first.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_image_asyncA

Submit async image generation task (qwen-image-plus, qwen-image). Returns task_id for polling.

ParametersJSON Schema

Name	Required	Description
`seed`	No	Random seed [0, 2147483647].
`size`	No	Size. Options: 1664928 (16:9), 14721104 (4:3), 13281328 (1:1), 11041472 (3:4), 9281664 (9:16). Default: 1664928.
`model`	No	Model. Default: qwen-image-plus. Options: qwen-image-plus, qwen-image.
`prompt`	Yes	Image generation prompt. Max 800 chars.
`watermark`	No	Add watermark. Default: false.
`prompt_extend`	No	Intelligent prompt rewriting. Default: true.
`negative_prompt`	No	Negative prompt. Max 500 chars.

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It discloses async behavior and polling, but lacks details on side effects, rate limits, or failure handling. Minimal but not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, front-loaded with purpose, and contains no extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 7 parameters and no output schema, the description covers the essential async polling workflow but omits error handling, timeouts, and result format. Adequate given sibling tools for check and download.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the description adds no extra parameter meaning. Baseline of 3 is appropriate; the description does not enhance understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (submit async image generation task) and the resource (qwen-image-plus, qwen-image), and distinguishes it from siblings like generate_image_sync by specifying async and returning task_id for polling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for non-blocking generation and mentions polling, but does not explicitly compare to generate_image_sync or provide when-not-to-use scenarios. Context signals list siblings, aiding inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_image_syncA

Generate images synchronously using Qwen-Image 2.0 series (qwen-image-2.0-pro, qwen-image-2.0, qwen-image-max). One request returns result directly.

ParametersJSON Schema

Name	Required	Description
`n`	No	Number of images (1-6). Default: 1.
`seed`	No	Random seed [0, 2147483647].
`size`	No	Size "widthheight". Default 20482048. Options: 26881536, 15362688, 20482048, 23681728, 1728*2368.
`model`	No	Model name. Default: qwen-image-2.0-pro. Options: qwen-image-2.0-pro, qwen-image-2.0, qwen-image-max.
`prompt`	Yes	Image generation prompt. Chinese/English. Max 1300 tokens.
`watermark`	No	Add watermark. Default: false.
`prompt_extend`	No	Intelligent prompt rewriting. Default: true.
`negative_prompt`	No	Negative prompt. Max 500 chars.

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavioral traits. It mentions synchronous execution and direct return, but lacks details on rate limits, auth requirements, mutation side effects, or potential errors. For a generation tool, this is insufficient transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two efficient sentences: first clearly states purpose and models, second adds synchronous behavior. No wasted words. Front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While parameters are well-specified in schema, the description lacks clarity on return value format (e.g., image URL or base64). Given no output schema, this gap reduces completeness for an agent to correctly process the response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with each parameter described. The description adds the context of the model series and synchronous nature but does not enhance meaning for individual parameters beyond schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Generate images synchronously using Qwen-Image 2.0 series', specifying the action (generate images), the resource (images via specific model series), and the modality (synchronous). This distinguishes it from sibling tools like generate_image_async.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies synchronous usage ('returns result directly'), providing some context but does not explicitly state when to use this tool over alternatives (e.g., async generation or task status checking). No when-not-to-use or prerequisite guidance is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

4 tool updatesv2.0.0Jul 28, 2026
- First observedcheck_task_status
- First observeddownload_image
- First observedgenerate_image_async
- First observedgenerate_image_sync

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0

Scored 2026-07-28 06:30 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

ActivityMaintained

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

fengyinxia-jimeng-mcp
ai.smithery
Create images and videos from prompts, with options for image mixing, reference images, and start/…
Image & Video Processing Multimedia Processing
2
dora-mcp AOAuth
io.github.Saga-Labs
Multi-model AI image and video generator. 14 models behind one OAuth-secured MCP endpoint.
AI & Machine Learning Image & Video Processing
42
FOTOhub Creative AI
app.fotohub
Generate images, video, music, voice and 3D through one API. 30 tools, 200+ models.
Image & Video Processing Audio Processing AI & Machine Learning
2
CCAPI A
ai.ccapi
Image, video, music and text generation across 100+ models through one endpoint.
AI & Machine Learning Image & Video Processing Audio Processing
111

Related MCP Servers

ModelScope Image MCP Server
Image & Video Processing Multimedia Processing App Automation
zym9863
A
license
C
quality
C
maintenance
Enables users to generate high-quality images using ModelScope's Qwen-Image model through natural language prompts. Supports async task processing with both image URL and base64 encoded data output options.
Updated 6 months ago (2026-03-26 15:28 UTC)
1
2
MIT
Seedream 4.0 MCP Server
Image & Video Processing Multimedia Processing App Automation
joeseesun
A
license
Not graded
quality
D
maintenance
Enables AI image generation using Volcano Engine's Seedream 4.0 API with text-to-image, image-to-image, multi-image fusion capabilities, built-in prompt templates, and automatic cloud storage integration.
Updated 10 months ago (2025-11-18 09:56 UTC)
19
MIT
Volcengine Image Generation
Image & Video Processing Multimedia Processing
stvlynn
F
license
B
quality
D
maintenance
Enables AI-powered text-to-image generation using Volcengine's API with support for multiple image sizes, customizable parameters like guidance scale and seed, and flexible output formats.
Updated a year ago (2025-08-21 10:48 UTC)
1
-
SeeDream Image MCP
Image & Video Processing Multimedia Processing
hongxianzhi
A
license
Not graded
quality
D
maintenance
Enables AI-powered image generation using Volcano Engine's SeeDream 4.0 model. Supports custom sizes, reference images, and automatic prompt generation without complex prompting.
Updated 8 months ago (2026-01-11 05:06 UTC)
14
MIT