MCP-IMAGE-GENERATOR/README.md

<p align="center">
  <img src="logo.png" width="200" alt="MCP Image Generator Logo">
</p>

<h1 align="center">MCP Image Generator</h1>

<p align="center">
MCP server for AI image generation. Works with <b>Claude Code</b>, <b>Cursor</b>, <b>Claude Desktop</b>, <b>OpenCode</b>, <b>Charm (Crush/Mods)</b>, and any MCP-compatible AI agent.
</p>

**Providers supported** (image models only):
- **OpenRouter** (default) — Gemini Flash Image, FLUX 2, Sourceful Riverflow, GPT-5 Image
- **Together AI** — FLUX.1 Schnell/Dev/Pro, Stable Diffusion XL
- **Replicate** — FLUX Schnell, FLUX 1.1 Pro, SDXL, Ideogram
- **fal.ai** — FLUX Dev/Schnell/2 Pro, Recraft V3

## Quick Start

No install needed — just use `npx`:

```bash
OPENROUTER_API_KEY="sk-or-v1-..." npx -y mcp-image-generator
```

## Tools

### `generate_image`
Generate an image from a text prompt.

| Parameter | Type | Description |
|-----------|------|-------------|
| `prompt` | string (required) | Text description of the image |
| `model` | string | Model ID (e.g. `google/gemini-2.5-flash-image`) |
| `provider` | string | `openrouter` (default), `together`, `replicate`, `fal` |
| `aspect_ratio` | string | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3` |
| `image_size` | string | `1K` (default), `2K`, `4K` |
| `negative_prompt` | string | What to exclude (not all providers support this) |
| `seed` | number | Random seed for reproducibility |
| `save_to` | string | Custom file path to save the image |

### `list_providers`
List all configured providers and their available image models.

| Parameter | Type | Description |
|-----------|------|-------------|
| `provider` | string | Filter by provider name |

---

## Setup for AI Agents / IDEs

### Claude Code

```bash
claude mcp add --scope user --transport stdio image-gen \
  --env OPENROUTER_API_KEY=sk-or-v1-xxx \
  -- npx -y mcp-image-generator
```

Or create `.mcp.json` in your project root:
```json
{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["-y", "mcp-image-generator"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}
```

### Cursor

Edit `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["-y", "mcp-image-generator"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}
```

### Claude Desktop

Edit the config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["-y", "mcp-image-generator"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}
```

### OpenCode (by SST)

Edit `~/.config/opencode/opencode.json` or `opencode.json` in project root:
```json
{
  "mcp": {
    "image-gen": {
      "type": "local",
      "command": ["npx", "-y", "mcp-image-generator"],
      "environment": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      },
      "enabled": true,
      "timeout": 120000
    }
  }
}
```

### Charm Crush

Add to `crush.json` in your project root:
```json
{
  "mcp": {
    "image-gen": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-image-generator"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-..."
      }
    }
  }
}
```

### Charm Mods

Edit `mods.yml` (`mods --settings`):
```yaml
mcp-servers:
  image-gen:
    command: [npx]
    args:
      - -y
      - mcp-image-generator
    env:
      - OPENROUTER_API_KEY=sk-or-v1-...
```

### Any MCP-compatible agent

This server uses **stdio transport** (JSON-RPC over stdin/stdout). Any agent that supports MCP stdio can use it:

```bash
npx -y mcp-image-generator

# Required environment variables (at least one)
OPENROUTER_API_KEY=...    # OpenRouter (default)
TOGETHER_API_KEY=...      # Together AI
REPLICATE_API_TOKEN=...   # Replicate
FAL_KEY=...               # fal.ai
```

## Using Multiple Providers

Set multiple API keys to use different providers:

```bash
export OPENROUTER_API_KEY="sk-or-v1-..."
export TOGETHER_API_KEY="..."
export FAL_KEY="..."
```

Then specify the provider when generating:
```
generate_image(prompt="a cat", provider="together", model="black-forest-labs/FLUX.1-schnell")
```

## Environment Variables

| Variable | Provider | Required |
|----------|----------|----------|
| `OPENROUTER_API_KEY` | OpenRouter | At least one |
| `TOGETHER_API_KEY` | Together AI | provider key |
| `REPLICATE_API_TOKEN` | Replicate | is required |
| `FAL_KEY` | fal.ai | |
| `IMAGE_OUTPUT_DIR` | — | Optional. Default: `~/generated-images/` |

## License

MIT