# Image Gen [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/nuver-labs/image-gen-mcp  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/image-gen

## Description
Generate and edit images from your coding agent with Gemini and OpenAI, using your own API keys.

## Tools
Capabilities this server exposes over MCP:

- **generate_image** — Text prompt to one or more image files. Returns the absolute saved paths.
- **edit_image** — Edit or combine existing images with a text instruction. Never overwrites the sources.
- **list_capabilities** — Which providers are configured, default models, and the output directory rules.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "image-gen": {
    "command": "npx",
    "args": ["-y","@nuver-labs/image-gen-mcp"]
  }
}
```

## Documentation & README

# image-gen-mcp

[![npm](https://img.shields.io/npm/v/@nuver-labs/image-gen-mcp)](https://www.npmjs.com/package/@nuver-labs/image-gen-mcp)
[![CI](https://github.com/nuver-labs/image-gen-mcp/actions/workflows/ci.yaml/badge.svg)](https://github.com/nuver-labs/image-gen-mcp/actions/workflows/ci.yaml)
[![license](https://img.shields.io/npm/l/@nuver-labs/image-gen-mcp)](https://github.com/nuver-labs/image-gen-mcp/blob/main/LICENSE)
[![Node](https://img.shields.io/node/v/@nuver-labs/image-gen-mcp)](https://nodejs.org)

Generate and edit images from your coding agent, with your own API keys. Ask for a
blog cover, a logo tweak, or a placeholder illustration, and the file lands
directly in your project where the agent can read it and iterate.

Google Gemini image models (the Nano Banana family) and OpenAI GPT image models
behind one interface. Configure one provider or both.

![A terminal window emitting a gradient ribbon that resolves into three generated image thumbnails](https://raw.githubusercontent.com/nuver-labs/image-gen-mcp/main/assets/hero.jpg)

<sub>This banner and the repository's social preview card were both generated by
this server, with `gemini-3.1-flash-image` at 16:9 2K. Prompts are in
[assets/README.md](https://github.com/nuver-labs/image-gen-mcp/blob/main/assets/README.md).</sub>

## Install

```bash
claude mcp add image-gen --scope user \
  --env GEMINI_API_KEY=your-gemini-key \
  --env OPENAI_API_KEY=your-openai-key \
  -- npx -y @nuver-labs/image-gen-mcp
```

Start a new Claude Code session to pick it up, then check `claude mcp list`.

Three things that trip people up:

- **At least one option must sit between the last `--env` and the server name.**
  Above, `--scope` does that job. Put the name straight after an `--env` pair and
  the CLI reads it as another `KEY=value`.
- **`--` before the command is mandatory.** Without it the server's own arguments
  get parsed as Claude Code's.
- Drop the `--env` line for any provider you do not use. You need at least one.

Get keys from [Google AI Studio](https://aistudio.google.com/apikey) and the
[OpenAI platform](https://platform.openai.com/api-keys).

### Other clients

Same package everywhere. For `.mcp.json` (project scope, commit it) and Claude
Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "image-gen": {
      "command": "npx",
      "args": ["-y", "@nuver-labs/image-gen-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-key",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}
```

Claude Code also accepts a per-server `"timeout": 600000`, which Claude Desktop
does not. Cursor uses the same shape in `.cursor/mcp.json`. On Windows, GUI hosts
cannot always find `npx`, so use `"command": "cmd"` with
`"args": ["/c", "npx", "-y", "@nuver-labs/image-gen-mcp"]`.

## Use it

Just ask, in plain language:

- "Generate a 16:9 hero image of a lighthouse at dusk and save it to `assets/hero.png`"
- "Take `public/logo.png` and give it a transparent background"
- "Create 3 variations of a flat paper airplane icon, square, into `design/drafts/`"

The agent calls `generate_image` or `edit_image` with an absolute `output_path`
inside your project, the file lands on disk, and the agent can then read the saved
path to look at the result and refine it. If a call fails, ask it to run
`list_capabilities` to see what is actually configured.

## Tools

| Tool | What it does |
|---|---|
| `generate_image` | Text prompt to one or more image files. Returns the absolute saved paths. |
| `edit_image` | Edit or combine existing images with a text instruction. Never overwrites the sources. |
| `list_capabilities` | Which providers are configured, default models, and the output directory rules. |

### generate_image

| Argument | Type | Notes |
|---|---|---|
| `prompt` | string, required | Subject, style, composition, colors, any text to render |
| `output_path` | string | Absolute file path (.png/.jpg/.webp) or a directory. Given a directory, the filename is slugified from the prompt |
| `provider` | `gemini` \| `openai` | Overrides the default provider |
| `model` | string | Gemini: gemini-3.1-flash-image (default), gemini-3.1-flash-lite-image, gemini-3-pro-image, gemini-2.5-flash-image. OpenAI: gpt-image-2 (default), gpt-image-1.5, gpt-image-1, gpt-image-1-mini |
| `aspect_ratio` | `1:1` `2:3` `3:2` `3:4` `4:3` `9:16` `16:9` `21:9` | Exact on Gemini and gpt-image-2. Older OpenAI models approximate: landscape 1536x1024, portrait 1024x1536 |
| `n` | 1-4 | Gemini generates sequentially, so n>1 is slower there |
| `quality` | `low` `medium` `high` `auto` | OpenAI only. `low` for cheap drafts |
| `background` | `transparent` `opaque` `auto` | OpenAI only. Ideal for logos and icons. Needs gpt-image-1.5 or older, so `transparent` on gpt-image-2 auto-switches to gpt-image-1.5 and says so in the result |
| `image_size` | `1K` `2K` `4K` | Gemini 3.x only |
| `return_image` | boolean | Also return the first image inline so the model can see it without a read. Costs context tokens |

### edit_image

Everything above, plus:

| Argument | Type | Notes |
|---|---|---|
| `source_paths` | string[], required | 1-16 absolute paths (.png/.jpg/.jpeg/.webp). The first is the edit target, the rest are references. Gemini works best with 1-3 |
| `input_fidelity` | `low` \| `high` | OpenAI only. `high` preserves faces, logos, and fine detail. Ignored on gpt-image-2, which is always high fidelity |

When `output_path` is omitted, the result is saved next to the first source image.

### list_capabilities

No arguments. Reports configured providers as booleans (never key values), the
default provider and models, known model options, the output directory fallback
chain, and any directory restriction in force.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `GEMINI_API_KEY` | (unset) | Enables the Gemini provider |
| `OPENAI_API_KEY` | (unset) | Enables the OpenAI provider |
| `IMAGE_GEN_MCP_DEFAULT_PROVIDER` | key-based | `gemini` or `openai`. When unset: gemini if its key is set, else openai |
| `IMAGE_GEN_MCP_GEMINI_MODEL` | `gemini-3.1-flash-image` | Default Gemini model |
| `IMAGE_GEN_MCP_OPENAI_MODEL` | `gpt-image-2` | Default OpenAI model |
| `IMAGE_GEN_MCP_OUTPUT_DIR` | (unset) | Fallback output directory when a call passes no `output_path` |
| `IMAGE_GEN_MCP_ALLOWED_DIRS` | (unset) | Comma separated directories that all reads and writes are confined to. See [Security](#security) |
| `IMAGE_GEN_MCP_TIMEOUT_MS` | `180000` | Per-request timeout to the provider API |
| `IMAGE_GEN_MCP_LOG_FILE` | `~/.image-gen-mcp/images.jsonl` | JSONL ledger path. Absolute path to relocate, `none` to disable the file |

With no `output_path`, files go to the first of: `IMAGE_GEN_MCP_OUTPUT_DIR`,
`CLAUDE_PROJECT_DIR` (set by Claude Code, points at the current project), the
server working directory.

## Security

This server runs locally with your full user privileges and is not sandboxed by
the MCP client. Worth understanding before you grant it blanket tool approval.

**What it can do.** Writes image files to disk. Reads the image files you point
`edit_image` at. Sends your prompt, and any `edit_image` source image, to the
provider you selected. Makes billable API calls. That is the whole surface: three
tools, no shell execution, no arbitrary URL fetching, no telemetry.

**File access.** The model chooses `output_path` and `source_paths`, and by
default they are unrestricted, because that is what makes the tool useful: your
agent saves into whichever project you are working in. Note that Claude Code's
working-directory boundary does not extend to MCP servers, and Anthropic
[does not security-audit third-party MCP servers](https://code.claude.com/docs/en/security).

To draw a hard boundary, set `IMAGE_GEN_MCP_ALLOWED_DIRS`:

```bash
IMAGE_GEN_MCP_ALLOWED_DIRS=/Users/you/projects,/Users/you/Desktop
```

Every output path and every `edit_image` source must then resolve inside one of
those roots. Paths are compared after `realpath` resolution, so a symlink pointing
out of a root is refused, and containment uses path segments rather than a string
prefix, so a sibling directory like `/Users/you/projects-private` does not slip
through. If none of the configured entries exist, the server refuses all file
access rather than silently running unrestricted.

**API keys.** Keys are read only from the environment, passed to the provider SDK
constructors, and used nowhere else. They are never logged, never written to the
ledger, and never returned by `list_capabilities`, which reports booleans.

The risk is where you put them, not what this server does with them. Keys inlined
into `~/.claude.json` or `claude_desktop_config.json` sit in plaintext, readable by
any process running as you, and an agent asked to read its own config can print
them into a transcript. Prefer exporting from a shell profile or a secret manager,
`chmod 600` the config files, and use a dedicated key with a spend limit rather
than a shared production key.

**Spend.** There is no built-in rate limit or cap. An agent in a retry loop can
generate a lot of images quickly. Set
[OpenAI hard spend limits](https://platform.openai.com/settings/organization/limits)
and Google Cloud budget alerts.

**Local log.** The ledger at `~/.image-gen-mcp/images.jsonl` contains a truncated
copy of each prompt in plaintext and grows without bound. Disable it with
`IMAGE_GEN_MCP_LOG_FILE=none`, and do not commit it.

**Prompt injection.** Tool results re-enter the model's context. Prefer per-call
approval over blanket-allowing this server, and glance at the output path and any
`edit_image` source path when approving. Pin a version and review the diff before
upgrading.

Found a vulnerability? See [SECURITY.md](https://github.com/nuver-labs/image-gen-mcp/blob/main/SECURITY.md). Please do not open a
public issue.

## Logging

Every successful call records one structured JSON entry, two ways:

- **stderr**, always: one `[image-gen-mcp] image {...}` line, visible in `/mcp`
  output and Claude Code logs.
- **JSONL ledger**, on by default: the same JSON appended to
  `~/.image-gen-mcp/images.jsonl`, one line per call. Ledger write failures never
  break a generation, they warn once on stderr.

Each entry captures the provider, model, requested size, elapsed seconds, a
truncated prompt with its full character count, token usage when the provider
reports it, and per-image details: saved path, byte size, human-readable size,
mime type, and actual pixel dimensions.

```bash
tail -n 20 ~/.image-gen-mcp/images.jsonl
jq 'select(.usage) | .usage.totalTokens' ~/.image-gen-mcp/images.jsonl
```

## Costs

Every call hits a paid API, typically cents per image, varying by provider, model,
quality, and size. Cheap options for drafts: OpenAI `quality: low` (roughly $0.006
for a low-quality 1024x1024 on gpt-image-2) or `gpt-image-1-mini`, and Gemini
`gemini-3.1-flash-lite-image`. Gemini's `gemini-2.5-flash-image` may have a free
tier on unbilled keys, so `IMAGE_GEN_MCP_GEMINI_MODEL=gemini-2.5-flash-image`
makes it the default.

## Timeouts

Generation takes roughly 10 to 120 seconds depending on model and size. Claude
Code's defaults are generous and this server sends progress notifications during
long calls, so no tuning is normally needed. If you set a tight global
`MCP_TOOL_TIMEOUT`, add a per-server `"timeout": 600000` in `.mcp.json`.

## Troubleshooting

- Server logs go to stderr with an `[image-gen-mcp]` prefix. Claude Code surfaces
  them in `/mcp` output and its logs.
- **Registered but no tools**: start a new session, then check `claude mcp list`
  and `claude mcp get image-gen`.
- **`Provider 'x' is not configured`**: that key is missing from the MCP server
  environment. Re-register with the `--env` flag or edit your config.
- **Output is outside the allowed directories**: `IMAGE_GEN_MCP_ALLOWED_DIRS` is
  set. Run `list_capabilities` to see the roots.
- **Response too large**: `return_image` inlines a full image and can exceed the
  MCP output token limit (`MAX_MCP_OUTPUT_TOKENS`, default 25k). Leave it off and
  let the agent read the saved file.
- **Gemini refusal**: the error includes the finish reason and any provider text.
  Rephrase the prompt.

## Build from source

Requires Node 22+ and pnpm.

```bash
git clone https://github.com/nuver-labs/image-gen-mcp.git
cd image-gen-mcp
pnpm install
pnpm build
```

Then point your client at `node /abs/path/to/image-gen-mcp/dist/index.js` instead
of `npx -y @nuver-labs/image-gen-mcp`.

```bash
pnpm test      # unit tests, no API keys needed
pnpm inspect   # list the tools over real MCP stdio

# Live tests. These cost real API credits.
GEMINI_API_KEY=... node dist/smoke.js --provider gemini
OPENAI_API_KEY=... node dist/smoke.js --provider openai
node dist/smoke.js --provider gemini --edit ./smoke-output/smoke-gen-gemini.png
```

## Contributing

Bug reports, provider quirk fixes, and documentation improvements are welcome.
See [CONTRIBUTING.md](https://github.com/nuver-labs/image-gen-mcp/blob/main/CONTRIBUTING.md). For anything larger, open an issue first.

Planned: OpenAI mask and inpainting support, migration off the legacy Gemini
`generateContent` image path to the Interactions API, and more providers.

## License

[MIT](https://github.com/nuver-labs/image-gen-mcp/blob/main/LICENSE)

---

Built by [Nuver Labs](https://nuverlabs.com).