image-forge-mcp

A powerful MCP (Model Context Protocol) server for image processing, supporting multiple AI providers including OpenAI, Google Gemini, Ideogram, and any OpenAI-compatible relay/proxy endpoints.

Features

• Multi-provider support: OpenAI (DALL-E 2/3, GPT-Image-1), Google Gemini, Ideogram V3, and any OpenAI-compatible endpoint
• Relay station support: Configure custom baseUrl to route through any proxy or relay service
• 4 core operations: Text-to-image, image editing, image variation, and image analysis
• Flexible configuration: JSON config with environment variable interpolation (${ENV_VAR})
• Auto provider routing: Automatically selects the best available provider based on capability
• Async task support: Long-running tasks can be submitted async and polled later

MCP Tools

Tool	Description
image_generate	Generate images from text prompts
image_edit	Edit images with inpainting and masks
image_variation	Create variations of existing images
image_analyze	Analyze and describe image content
image_task_get	Check status of async tasks

Installation

1. Clone and build

git clone <repo>
cd image-forge-mcp
npm install
npm run build

2. Configure

cp config.example.json config.json

Edit config.json and set your API keys (or use environment variables):

{
  "providers": [
    {
      "id": "openai-main",
      "type": "openai_compatible",
      "apiKey": "${OPENAI_API_KEY}",
      "baseUrl": "https://api.openai.com",
      ...
    }
  ]
}

3. Set environment variables

export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=AIza...
export IDEOGRAM_API_KEY=...

4. Register with Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "image-forge": {
      "command": "node",
      "args": ["/absolute/path/to/image-forge-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "AIza...",
        "IDEOGRAM_API_KEY": "...",
        "IMAGE_FORGE_CONFIG": "/absolute/path/to/image-forge-mcp/config.json"
      }
    }
  }
}

Restart Claude Desktop after editing.

Using with Relay/Proxy Services

To use a relay station (e.g., api2d, openrouter, or any OpenAI-compatible proxy):

{
  "id": "my-relay",
  "type": "openai_compatible",
  "apiKey": "${RELAY_API_KEY}",
  "baseUrl": "https://your-relay-station.com",
  "models": {
    "textToImage": ["dall-e-3", "flux-pro-1.1", "gpt-image-1"],
    "imageAnalyze": ["gpt-4o-mini"]
  },
  "openaiCompat": {
    "authMode": "bearer"
  }
}

Some relay stations use a different auth header. Use authMode: "api-key-header" with apiKeyHeaderName for those.

Configuration Reference

Environment Variables

Variable	Description	Default
IMAGE_FORGE_CONFIG	Path to config.json	./config.json
OPENAI_API_KEY	OpenAI API key	-
GEMINI_API_KEY	Google AI Studio API key	-
IDEOGRAM_API_KEY	Ideogram API key	-
LOG_LEVEL	Log level (debug/info/warn/error)	info
HTTPS_PROXY	HTTP proxy for outbound requests	-

Provider Types

• openai_compatible: Supports DALL-E, GPT-Image, and any OpenAI-format API
• gemini: Google Gemini image generation API
• ideogram: Ideogram V3 API

Supported Models (Phase 1)

OpenAI-compatible:

• gpt-image-1 — Latest GPT image model
• dall-e-3 — DALL-E 3 (text-to-image only)
• dall-e-2 — DALL-E 2 (supports edit + variation)
• Any model exposed by your relay station

Gemini:

• gemini-2.0-flash-preview-image-generation
• gemini-3.1-pro-image-preview

Ideogram:

• V_3 — Ideogram V3
• V_3_TURBO — Ideogram V3 Turbo (faster)

Example Usage in Claude

Generate an image of a sunset over Tokyo with cherry blossoms, photorealistic, 16:9

Edit this image [attach image] to add a rainbow in the sky

What's in this image? [attach image]

Create a variation of this image [attach image] with a warmer color tone

License

MIT