image-gen-mcp

English | 中文

A multi-provider AI image generation MCP server that gives image generation capabilities to agents without them (e.g. Claude Code).

• Unified abstraction: ImageProvider interface — adding a provider = one adapter file + one registry entry

• Multi-provider failover: priority routing, retries, automatic fallback to the next provider until success or the max failover count

• Three-layer config: defaults → environment variables → CLI args (args win)

• SDK selection (by priority): official SDK → compatible SDK → fetch. Current state:

  • google — official @google/genai SDK (Gemini image models / Imagen)

  • openai / openrouter / grok / siliconflow / volcengine — official openai SDK

  • zhipu (CogView) / dashscope (Wan) — no active official Node SDK, but their image APIs are OpenAI-compatible, reusing the openai SDK (compatible-SDK path)

• Output modes: url / base64 / file (saved locally), configurable globally or per call

• Transport: stdio, installable via npx

Quick Start

# After publishing
npx @inferai/image-gen-mcp

# Local development
pnpm install && pnpm build
node dist/index.js

Configure it as a stdio MCP server in your client. Windows — Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json; Claude Code: ~/.claude.json (C:\Users\<user>\.claude.json). cmd /c is required to resolve npx:

{
  "mcpServers": {
    "image-gen": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@inferai/image-gen-mcp"],
      "env": {
        "IMAGE_MCP_OPENAI_API_KEY": "sk-...",
        "IMAGE_MCP_ZHIPU_API_KEY": "..."
      }
    }
  }
}

Linux / macOS — Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux); Claude Code: ~/.claude.json:

{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["-y", "@inferai/image-gen-mcp"],
      "env": {
        "IMAGE_MCP_OPENAI_API_KEY": "sk-...",
        "IMAGE_MCP_ZHIPU_API_KEY": "..."
      }
    }
  }
}

Providers are auto-discovered: a provider is enabled iff its API key is configured — no provider list to maintain. Set IMAGE_MCP_<ID>_API_KEY (or --<id>-api-key) for exactly the providers you want.

Related MCP server: imagen-mcp

Configuration

All settings follow a three-layer override: defaults → IMAGE_MCP_* env vars → --key=value args.

Global

Providers (<ID> per table below)

Example (env vars):

export IMAGE_MCP_OPENAI_API_KEY=sk-...
export IMAGE_MCP_ZHIPU_API_KEY=...
export IMAGE_MCP_GOOGLE_API_KEY=...
export IMAGE_MCP_MAX_RETRIES=3
export IMAGE_MCP_MAX_DEGRADATIONS=2

Example (args override):

npx @inferai/image-gen-mcp \
  --openai-api-key=sk-... \
  --zhipu-api-key=... \
  --max-retries=0 \
  --max-degradations=1 \
  --output-mode=file \
  --output-dir=./images

MCP Tools

generate_image

Returns JSON with the actual provider/model used and the full failover attempt log:

{
  "provider": "openai",
  "model": "gpt-image-1",
  "images": [{ "format": "url", "data": "https://...", "mimeType": "image/png" }],
  "attempts": [
    { "provider": "zhipu", "model": "cogview-4-flash", "status": "failed", "error": "429 rate limited" },
    { "provider": "openai", "model": "gpt-image-1", "status": "success" }
  ]
}

• file mode: images are written to IMAGE_MCP_OUTPUT_DIR, the local absolute path is returned

• url mode: base64 results are converted to data: URIs automatically

list_providers

Lists enabled providers (id / default model / endpoint / priority); no API key required.

Retry & Failover Semantics

Try providers in priority ascending order; within a provider: retryable errors
(network/timeout/429/5xx) retry with exponential backoff up to maxRetries,
non-retryable (401/400 etc.) fail it immediately; on provider failure fall back to
the next, up to maxDegradations times; total failure returns an error with the full
attempt summary.

• max-retries=0: each provider is tried once

• max-degradations=0: only the highest-priority provider is used

• API keys are sanitized in all error messages and attempt logs

Development

pnpm install
pnpm dev        # rslib watch
pnpm test       # rstest unit tests
pnpm check      # biome format + lint
pnpm build      # build dist
node scripts/smoke.mjs   # stdio end-to-end smoke test (requires a configured key)

Integration tests need real API keys and are not part of the suite; verify manually:

IMAGE_MCP_OPENAI_API_KEY=sk-... node dist/index.js   # then call via an MCP client

Debugging with MCP Inspector:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js --xxx-api-key=xxx --xxx2-api-key=xxx

Publishing

Publishing is automated (.github/workflows/publish.yml with the changesets/action select-mode flow): push to main creates a version PR, and merging it publishes to npm automatically.

pnpm changeset   # record changes (the only manual step), then merge the PR to main

pnpm release exists as a manual fallback. CI runs check + test + build on every PR; local git hooks (simple-git-hooks) run pnpm check pre-commit and pnpm format pre-push.

License

MIT