# 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

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

### 2. Configure

```bash
cp config.example.json config.json
```

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

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

### 3. Set environment variables

```bash
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`:

```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):

```json
{
  "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