mcp-duojie-image

MCP server for image generation via duojie.games GPT image API.

Features

• Text-to-image generation with gpt-image-2
• Reference image editing via local image paths
• Async submission with task status lookup
• File saving with overwrite/conflict handling
• Verified size templates for 1K, 2K, and 4K

Configuration

Required:

| Variable | Default | Description | |---|---|---| | DUOJIE_API_KEY | required | duojie.games API key | | DUOJIE_BASE_URL | https://api.duojie.games | API base URL |

Tool: generate_image

Generates an image asynchronously and saves it to disk.

Required parameters:

| Parameter | Type | Description | |---|---|---| | prompt | string | Image prompt | | output_dir | string | Absolute output directory | | output_filename | string | Filename without extension |

Optional parameters:

| Parameter | Type | Default | Description | |---|---|---:|---| | size | 1K | 2K | 4K | 1K | Output size tier | | aspect_ratio | 1:1 | 3:2 | 2:3 | 16:9 | 9:16 | 1:1 | Verified ratio template | | reference_images | string[] | - | Local reference image paths | | format | string | png | Output format | | overwrite | boolean | false | Overwrite existing file | | negative_prompt | string | - | Content to avoid | | silent | boolean | false | Disable desktop notification |

Response:

{
  "success": true,
  "status": "submitted",
  "task_id": "uuid",
  "message": "已提交异步生成；如需诊断失败原因，可调用 check_image_task"
}

Tool: check_image_task

Checks async task status and failure details.

| Parameter | Type | Description | |---|---|---| | task_id | string | Task id returned by generate_image |

Done response:

{
  "success": true,
  "task_id": "uuid",
  "status": "done",
  "saved_path": "D:/images/output.png"
}

Failed response:

{
  "success": false,
  "task_id": "uuid",
  "status": "failed",
  "error": "E_PROVIDER_BAD_REQUEST",
  "message": "Upstream error details"
}

Verified GPT size templates

These templates were tested directly against /v1/images/generations; all returned the requested dimensions.

| size | 1:1 | 3:2 | 2:3 | 16:9 | 9:16 | |---|---:|---:|---:|---:|---:| | 1K | 1024x1024 | 1536x1024 | 1024x1536 | 1792x1024 | 1024x1792 | | 2K | 2048x2048 | 2304x1536 | 1536x2304 | 2560x1440 | 1440x2560 | | 4K | 2880x2880 | 3456x2304 | 2304x3456 | 3840x2160 | 2160x3840 |

512px is intentionally unsupported because direct API testing returned Invalid size ... below the current minimum pixel budget.

Example

generate_image(
  prompt="A futuristic city at sunset",
  size="2K",
  aspect_ratio="16:9",
  output_dir="D:/ai-images",
  output_filename="city_sunset"
)

check_image_task(task_id="uuid")