# openai-images-mcp

Generate and edit images with OpenAI's `gpt-image` and DALL·E models, exposed as [Model Context Protocol](https://modelcontextprotocol.io) tools. Supports `gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`, `dall-e-3`, and `dall-e-2`.

## Tools

| Tool | Purpose | Models |
| --- | --- | --- |
| `list_models` | List supported models and their capabilities (sizes, qualities, edit/variation support). | all |
| `generate_image` | Generate one or more images from a text prompt. | `gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`, `dall-e-3`, `dall-e-2` |
| `edit_image` | Edit existing images with a prompt and optional mask. | `gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`, `dall-e-2` |
| `create_variation` | Generate variations of an image. | `dall-e-2` only |

All generated files are saved to disk. Set `return_image_content: true` on any call to also receive the images as MCP image blocks (useful when the client should "see" the result, but adds a lot of tokens).

## Install

```bash
npm install
npm run build
```

## Configure your MCP client

### Claude Desktop / Claude Code

Add to `claude_desktop_config.json` (or your project's `.mcp.json`):

```json
{
  "mcpServers": {
    "dalle": {
      "command": "node",
      "args": ["/absolute/path/to/dalle-mcp/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "DALLE_OUTPUT_DIR": "/absolute/path/where/images/save"
      }
    }
  }
}
```

### Environment variables

| Variable | Purpose |
| --- | --- |
| `OPENAI_API_KEY` | **Required.** Your OpenAI API key. |
| `OPENAI_BASE_URL` | Optional. Override OpenAI base URL. |
| `OPENAI_ORG_ID` | Optional. |
| `OPENAI_PROJECT_ID` | Optional. |
| `DALLE_OUTPUT_DIR` | Optional. Default directory for saved images. Falls back to `~/dalle-mcp-output`. |
| `DALLE_DEFAULT_MODEL` | Optional. Model used when a tool call omits `model`. Default `gpt-image-1.5`. |

## Tool reference

### `generate_image`

Required: `prompt`.

Optional: `model`, `size`, `quality`, `n`, `background`, `output_format`, `output_compression`, `moderation`, `style`, `user`, `output_dir`, `filename_prefix`, `return_image_content`.

Model-specific notes:
- **GPT Image** (`gpt-image-1.5`, `gpt-image-1`, `gpt-image-1-mini`): sizes `auto|1024x1024|1536x1024|1024x1536`, qualities `auto|low|medium|high`. Supports `background`, `output_format`, `output_compression`, `moderation`.
- **DALL·E 3**: sizes `1024x1024|1792x1024|1024x1792`, qualities `standard|hd`, `n` must be 1, supports `style`.
- **DALL·E 2**: sizes `256x256|512x512|1024x1024`, quality `standard`.

### `edit_image`

Required: `prompt`, `images` (absolute paths, up to 16 for GPT Image).

Optional: `mask` (transparent pixels indicate editable regions), plus the generation options above. DALL·E 3 does not support edits.

### `create_variation`

DALL·E 2 only. Required: `image` (PNG, square, under 4MB).

Optional: `n`, `size` (`256x256|512x512|1024x1024`), `output_dir`, `filename_prefix`, `return_image_content`.

### `list_models`

No arguments. Returns a JSON document describing each model's sizes, qualities, and supported options — handy for the caller to consult before picking parameters.

## Development

```bash
npm run dev     # run with tsx, no build step
npm run build   # tsc to dist/
npm start       # node dist/index.js
```

The server speaks MCP over stdio, so you can drive it with any MCP-compatible client or manually by piping JSON-RPC messages to `node dist/index.js`.

## Notes

- DALL·E 2 and DALL·E 3 are deprecated by OpenAI and support ends **2026-05-12**; prefer the GPT Image family.
- GPT Image models always return base64 data; DALL·E models are asked for base64 as well so files can be saved without a second HTTP round-trip.