@alonetech/gpt-image-mcp

MCP stdio server and CLI for OpenAI-compatible image generation APIs.

It supports:

• Text-to-image: prompt only
• Image-to-image: prompt plus one or more reference images
• MCP stdio mode for MCP clients
• Direct CLI mode for local testing

Requirements

• Node.js 18.17 or newer
• An OpenAI-compatible image API base_url
• A bearer token for that API

CLI

Show help:

npx @alonetech/gpt-image-mcp --help

Text-to-image:

npx @alonetech/gpt-image-mcp generate \
  --base-url "https://api.openai.com/v1" \
  --token "YOUR_TOKEN" \
  --prompt "An orange cat wearing a space suit, movie poster style" \
  --output "./cat.png" \
  --size "1024x1024" \
  --quality "high" \
  --format "png"

Image-to-image:

npx @alonetech/gpt-image-mcp generate \
  --base-url "https://api.openai.com/v1" \
  --token "YOUR_TOKEN" \
  --prompt "Turn the references into a clean product image" \
  --image "./front.png" \
  --image "./side.jpg" \
  --output "./product.png"

On PowerShell, use backticks instead of backslashes for line continuation.

MCP Usage

Example MCP server config:

{
  "mcpServers": {
    "gpt-image": {
      "command": "npx",
      "args": [
        "-y",
        "@alonetech/gpt-image-mcp",
        "--base-url",
        "https://api.openai.com/v1",
        "--token",
        "YOUR_TOKEN"
      ]
    }
  }
}

For debugging client startup, add:

"--debug-log",
"D:\\tmp\\gpt-image-mcp-debug.log"

MCP Tool

Tool name:

generate_image

Required arguments:

• prompt: prompt describing the output image
• output: filesystem path where the generated image will be saved

Optional arguments:

• images: reference images as base64 strings or data URLs. Omit or pass an empty array for text-to-image mode.
• model: defaults to gpt-image-2
• size: defaults to auto
• quality: auto, low, medium, or high
• background: auto, transparent, or opaque

base_url and token are server startup configuration, not per-tool-call arguments.

Development

npm test
npm run pack:dry-run

Create a local package tarball:

npm pack

Test the tarball:

npx ./alonetech-gpt-image-mcp-0.1.0.tgz --help