mcp-duojie-image

MCP server for image generation via duojie.games API (Gemini Flash Image).

Features

• Text-to-image generation — generate images from prompts with configurable size and aspect ratio
• Reference image support — provide local image files as visual references (auto-compressed to 1024px long-side)
• Async mode — for long-running generations (especially with reference images), use async_mode: true to get a task_id immediately and poll for completion; prevents MCP client timeout
• Sync mode — for simple text-to-image generation without reference images, the default sync mode returns the result directly
• File saving — automatic output directory creation, conflict handling (overwrite flag, auto-incrementing filename suffix)
• Configurable output — size (512px/1K/2K/4K), aspect ratio, format

Installation

npx mcp-duojie-image

Or with a specific version:

npx [email protected]

Configuration

Set the DUOJIE_API_KEY environment variable:

export DUOJIE_API_KEY=sk-your-key-here

Or configure in your MCP client (e.g., Claude Desktop, Factory):

{
  "mcpServers": {
    "duojie-image": {
      "command": "node",
      "args": ["/path/to/mcp-duojie-image/dist/index.js"],
      "env": {
        "DUOJIE_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Optional environment variables:

| Variable | Default | Description | |----------|---------|-------------| | DUOJIE_API_KEY | (required) | API key | | DUOJIE_BASE_URL | https://api.duojie.ai/v1 | API endpoint | | DUOJIE_MODEL | gemini-2.0-flash-exp-image-generation | Model to use |

Tools

generate_image

Generate an image and save it to disk.

Required parameters:

• prompt (string) — Image description
• output_dir (string) — Output directory (absolute path)
• output_filename (string) — Output filename (no extension needed)

Optional parameters:

• reference_images (string[]) — Local image paths for reference. Images are auto-compressed to max 1024px long-side before sending to API.
• size ("512px" | "1K" | "2K" | "4K") — Output image size. Default: 1K
• aspect_ratio (string) — e.g., "16:9", "1:1"
• format (string) — Output format. Default: "png"
• model (string) — Model override
• overwrite (boolean) — Overwrite existing file. Default: false (auto-increments filename)
• negative_prompt (string) — What to avoid in the image
• async_mode (boolean) — When true, returns task_id immediately and generates in background. Recommended when using reference_images to avoid MCP client timeout. Default: false

Response (sync mode):

{ "success": true, "saved_path": "/absolute/path/to/image.png", "model": "gemini-..." }

Response (async mode):

{ "task_id": "uuid", "status": "pending" }

check_image_task

Check the status of an async image generation task.

Required parameters:

• task_id (string) — Task ID returned by generate_image with async_mode: true

Polling workflow:

1. Call generate_image with async_mode: true → get task_id
2. Call check_image_task with task_id every few seconds
3. When status is "done", retrieve saved_path from the response
4. If status is "failed", check error and message fields

Response:

{ "task_id": "uuid", "status": "done", "saved_path": "/path/to/image.png", "model": "gemini-..." }

Usage Examples

Simple text-to-image (sync)

generate_image(
  prompt="A sunset over the ocean, photorealistic",
  output_dir="/tmp/images",
  output_filename="sunset"
)

With reference image (use async_mode to avoid timeout)

generate_image(
  prompt="Same style as reference, but with mountains instead",
  reference_images=["/path/to/reference.png"],
  output_dir="/tmp/images",
  output_filename="mountain_scene",
  async_mode=true
)
→ { "task_id": "abc-123", "status": "pending" }

check_image_task(task_id="abc-123")
→ { "status": "running" }  # poll again

check_image_task(task_id="abc-123")
→ { "status": "done", "saved_path": "/tmp/images/mountain_scene.png" }

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Type check / lint
npm run lint

Architecture

src/
  index.ts       — MCP server, tool registration (generate_image, check_image_task)
  provider.ts    — HTTP client for image generation API
  resizer.ts     — Reference image compression (jimp, max 1024px long-side)
  task-queue.ts  — In-memory async task state machine (pending→running→done/failed, 30min TTL)
  config.ts      — Environment variable loading
  saver.ts       — File saving with conflict handling
  errors.ts      — Error codes (E_CONFIG_MISSING_KEY, E_PROVIDER_AUTH, etc.)

License

MIT