# imagent

> Image generation for your agents.

An MCP server that lets coding agents (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code and any other MCP client) **generate, edit and post-process images** and save them straight into your project.

It currently runs on OpenAI's GPT Image models (`gpt-image-2.6-flare` / `gpt-image-2.6-sunburst`). The provider layer is pluggable, so other backends can be added without changing the tools.

## Tools

| Tool | What it does | Costs money? |
| --- | --- | --- |
| `generate_image` | Text → image. PNG/JPEG/WebP, transparent backgrounds, **SVG** vector output, short **GIF** animations, custom sizes up to 3840px, 1–N variations. | Yes |
| `edit_image` | Image(s) + instruction → new image. Restyle, recolor, remove backgrounds, add or remove objects, or make a new asset that matches up to 16 reference images. Supports `mask` (inpainting) and `markup` (draw arrows or circles on what to change). | Yes |
| `process_image` | Local, deterministic ops: resize, crop, trim, pad, rotate, flip, blur, grayscale, flatten, and convert/compress to png/jpeg/webp/gif. Good for exact sizes (favicons, OG images, sprites). | No |
| `inspect_image` | Dimensions, format, size, frame count, and whether the image *actually* has transparent pixels. | No |

Every result includes the **saved file path**, dimensions, a transparency check and a small **preview** image, so the agent can look at what it made and iterate.

## Quick start

You need an OpenAI API key with image access.

### Claude Code

```bash
claude mcp add imagent -e OPENAI_API_KEY=sk-... -- npx -y @1mrnewton/imagent
```

### Cursor (`~/.cursor/mcp.json`) / Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "imagent": {
      "command": "npx",
      "args": ["-y", "@1mrnewton/imagent"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}
```

Using Bun? Swap `npx -y` for `bunx`.

> Generating at high quality can take 30–90 seconds. If your client times out, raise its MCP tool timeout (e.g. `MCP_TOOL_TIMEOUT=180000` for Claude Code).

## Configuration

All settings are environment variables:

| Variable | Default | |
| --- | --- | --- |
| `OPENAI_API_KEY` | — | Required. |
| `IMAGENT_OUTPUT_DIR` | `./generated-images` (or `~/Pictures/generated-images` when the client starts in `/` or `~`) | Where files go when no absolute `output_path` is given. |
| `IMAGENT_MODEL` | `gpt-image-2.6-flare` | Default model for `generate_image`. |
| `IMAGENT_EDIT_MODEL` | `gpt-image-2.6-sunburst` | Default model for `edit_image`. |
| `IMAGENT_QUALITY` | `medium` | Default quality: `low` · `medium` · `high` · `xhigh` · `max` · `auto`. |
| `IMAGENT_SVG_MODEL` | `gpt-5.4-mini` | Text model that writes SVG code when `format: "svg"` (OpenAI requires one). |
| `IMAGENT_MAX_N` | `4` | Most images per call, so a looping agent can't drain your credits. |
| `IMAGENT_PREVIEW_SIZE` | `512` | Longest edge of the preview returned to the model. |
| `IMAGENT_TIMEOUT_MS` | `300000` | OpenAI request timeout. |
| `OPENAI_BASE_URL`, `OPENAI_ORG_ID` | — | Optional, e.g. for a proxy or gateway. |

## Behavior notes

- **Never overwrites** an existing file unless `overwrite: true`. It saves `name-v2.png` instead.
- `output_path` ending in `/` is treated as a directory, and the file gets an automatic name from the prompt.
- The `output_path` extension picks the format when `format` isn't given (`hero.webp` → WebP).
- Inputs can be local paths, `~/` paths, `file://`, `http(s)://` or `data:` URLs. SVG and GIF inputs are converted to PNG before editing.
- SVG output is generate-only with `n=1`. An image model draws a reference and a text model (`svg_model`) writes the SVG. GIF output is generate-only.
- Without `size`, `edit_image` resizes its result back to the source dimensions, so edited assets drop in as replacements.
- Previews are small JPEGs, with transparent areas shown on a checkerboard, to keep the agent's context small.
- Transparent backgrounds need PNG, WebP or GIF.

## Costs

OpenAI bills image output by quality and size, plus input tokens for prompts and reference images. See [OpenAI's pricing page](https://openai.com/api/pricing/) for current rates. Draft with `quality: "low"` and make finals at `high`. `process_image` and `inspect_image` are always free.

## Development

```bash
bun install
bun run dev          # run the server over stdio
bun run inspect      # open the MCP Inspector against it
bun run typecheck
bun run build        # bundle to dist/ (runs on Node ≥ 20 or Bun)
```

To point a client at your local checkout instead of npm:

```json
{ "command": "bun", "args": ["run", "/absolute/path/to/imagent/src/index.ts"], "env": { "OPENAI_API_KEY": "sk-..." } }
```

### Adding a provider

1. Implement `ImageProvider` from [`src/providers/types.ts`](src/providers/types.ts) (`generate` and `edit`).
2. Register it in [`src/providers/index.ts`](src/providers/index.ts).
3. Select it with `IMAGENT_PROVIDER=<id>`.

The tools, file handling, previews and `process_image` stay the same for every provider.

## License

MIT