# Image Gen MCP

TypeScript MCP server for generating and editing images through OpenAI image models.

The server registers `generate_image` and `edit_image` tools, then writes the returned
image bytes to disk. Stdio mode writes to the requested absolute filepath; SSE and
streamable HTTP auto-save files and return image URLs.

## Env

| Name       | Required | Default               | Description                                                                                  |
| ---------- | -------- | --------------------- | -------------------------------------------------------------------------------------------- |
| `BASE_URL` | No       | AI SDK OpenAI default | OpenAI API URL prefix, for example `https://api.openai.com/v1`. Root URLs auto-append `/v1`. |
| `API_KEY`  | Yes      | -                     | OpenAI API key.                                                                              |
| `MODEL`    | No       | `gpt-image-2`         | OpenAI image model.                                                                          |
| `FILE_DIR` | No       | `./data`              | Directory for auto-saved files in SSE/HTTP mode. Docker defaults this to `/data`.            |

## Tool

### `generate_image`

Arguments:

| Name                 | Required | Default  | Description                                                                                       |
| -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------- |
| `prompt`             | Yes      | -        | Image prompt.                                                                                     |
| `filepath`           | Stdio    | -        | Stdio only. Absolute output path. Parent directories are created automatically.                   |
| `n`                  | No       | `1`      | Number of images, from `1` to `3`.                                                                |
| `size`               | No       | `auto`   | `auto`, `256x256`, `512x512`, `1024x1024`, `1536x1024`, `1024x1536`, `1792x1024`, or `1024x1792`. |
| `quality`            | No       | `medium` | `low`, `medium`, `high`, or `auto`.                                                               |
| `background`         | No       | -        | `transparent`, `opaque`, or `auto`.                                                               |
| `output_format`      | No       | `png`    | `png`, `jpeg`, `jpg`, or `webp`; `jpg` is sent as `jpeg`.                                         |
| `output_compression` | No       | -        | Compression level from `0` to `100`.                                                              |
| `moderation`         | No       | -        | `auto` or `low`.                                                                                  |
| `overwrite`          | Stdio    | `false`  | Stdio only. Allow replacing existing output files.                                                |

Known model size limits are validated before calling the upstream API. For example,
`gpt-image-*` models support `1024x1024`, `1536x1024`, and `1024x1536`; `dall-e-2`
supports `256x256`, `512x512`, and `1024x1024`.

For `n > 1`, a filepath like `/tmp/image.png` becomes `/tmp/image-1.png`,
`/tmp/image-2.png`, and so on.

In SSE and streamable HTTP modes, `filepath` and `overwrite` are not exposed. Generated
files are saved as `${FILE_DIR}/YYYY-MM-DD/<uuid>.<ext>` and returned with URLs like
`http://localhost:3000/file/YYYY-MM-DD/<uuid>.png`.

### `edit_image`

Arguments:

| Name                 | Required | Default  | Description                                                                                       |
| -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------- |
| `prompt`             | Yes      | -        | Edit instruction.                                                                                 |
| `image_path`         | Yes      | -        | Absolute path to the source image to edit.                                                        |
| `mask_path`          | No       | -        | Optional absolute path to the edit mask image.                                                    |
| `filepath`           | Stdio    | -        | Stdio only. Absolute output path. Parent directories are created automatically.                   |
| `n`                  | No       | `1`      | Number of edited images, from `1` to `3`.                                                         |
| `size`               | No       | `auto`   | `auto`, `256x256`, `512x512`, `1024x1024`, `1536x1024`, `1024x1536`, `1792x1024`, or `1024x1792`. |
| `quality`            | No       | `medium` | `low`, `medium`, `high`, or `auto`.                                                               |
| `background`         | No       | -        | Edited image background behavior.                                                                 |
| `output_format`      | No       | `png`    | `png`, `jpeg`, `jpg`, or `webp`; `jpg` is sent as `jpeg`.                                         |
| `output_compression` | No       | -        | Compression level from `0` to `100`.                                                              |
| `moderation`         | No       | -        | `auto` or `low`.                                                                                  |
| `overwrite`          | Stdio    | `false`  | Stdio only. Allow replacing existing output files.                                                |

The tool calls the OpenAI-compatible `/images/edits` endpoint with multipart form data.
Output files follow the same filepath and auto-save behavior as `generate_image`.

## Development

```bash
pnpm install
pnpm dev
```

Useful checks:

```bash
pnpm check
pnpm build
```

## Stdio MCP Config

```json
{
  "mcpServers": {
    "image-gen-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["image-gen-mcp"],
      "env": {
        "BASE_URL": "https://api.openai.com/v1",
        "API_KEY": "sk-...",
        "MODEL": "gpt-image-2"
      }
    }
  }
}
```

## Streamable HTTP

```json
{
  "mcpServers": {
    "image-gen-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "openai-base-url": "https://api.openai.com/v1",
        "openai-api-key": "sk-...",
        "openai-model": "gpt-image-2"
      }
    }
  }
}
```

Headers override the server-side env config; omit them to fall back to the env
values. The Docker image runs streamable HTTP on port 3000.

## SSE

The SSE transport lives in `src/sse.ts` and listens on `PORT` (default `4000`)
at `/mcp`, with messages posted to `/message`. Run it directly with
`pnpm start:sse`; it is not started by the Docker image.

```json
{
  "mcpServers": {
    "image-gen-mcp": {
      "type": "sse",
      "url": "http://localhost:4000/mcp",
      "headers": {
        "openai-api-key": "sk-..."
      }
    }
  }
}
```

## Docker

```bash
docker build -t image-gen-mcp .
docker run --rm -p 3000:3000 \
  # 也可忽略apiKey，让使用方 headers 中传递
  -e BASE_URL=https://api.openai.com/v1 \
  -e API_KEY=sk-... \
  -e MODEL=gpt-image-2 \
  -v image-gen-data:/data \
  image-gen-mcp
```