{
  "markdown": "# image-gen-mcp\n\n[![npm](https://img.shields.io/npm/v/@nuver-labs/image-gen-mcp)](https://www.npmjs.com/package/@nuver-labs/image-gen-mcp)\n[![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)\n[![license](https://img.shields.io/npm/l/@nuver-labs/image-gen-mcp)](https://github.com/nuver-labs/image-gen-mcp/blob/main/LICENSE)\n[![Node](https://img.shields.io/node/v/@nuver-labs/image-gen-mcp)](https://nodejs.org)\n\nGenerate and edit images from your coding agent, with your own API keys. Ask for a\nblog cover, a logo tweak, or a placeholder illustration, and the file lands\ndirectly in your project where the agent can read it and iterate.\n\nGoogle Gemini image models (the Nano Banana family) and OpenAI GPT image models\nbehind one interface. Configure one provider or both.\n\n![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)\n\n<sub>This banner and the repository's social preview card were both generated by\nthis server, with `gemini-3.1-flash-image` at 16:9 2K. Prompts are in\n[assets/README.md](https://github.com/nuver-labs/image-gen-mcp/blob/main/assets/README.md).</sub>\n\n## Install\n\n```bash\nclaude mcp add image-gen --scope user \\\n  --env GEMINI_API_KEY=your-gemini-key \\\n  --env OPENAI_API_KEY=your-openai-key \\\n  -- npx -y @nuver-labs/image-gen-mcp\n```\n\nStart a new Claude Code session to pick it up, then check `claude mcp list`.\n\nThree things that trip people up:\n\n- **At least one option must sit between the last `--env` and the server name.**\n  Above, `--scope` does that job. Put the name straight after an `--env` pair and\n  the CLI reads it as another `KEY=value`.\n- **`--` before the command is mandatory.** Without it the server's own arguments\n  get parsed as Claude Code's.\n- Drop the `--env` line for any provider you do not use. You need at least one.\n\nGet keys from [Google AI Studio](https://aistudio.google.com/apikey) and the\n[OpenAI platform](https://platform.openai.com/api-keys).\n\n### Other clients\n\nSame package everywhere. For `.mcp.json` (project scope, commit it) and Claude\nDesktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"image-gen\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nuver-labs/image-gen-mcp\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-gemini-key\",\n        \"OPENAI_API_KEY\": \"your-openai-key\"\n      }\n    }\n  }\n}\n```\n\nClaude Code also accepts a per-server `\"timeout\": 600000`, which Claude Desktop\ndoes not. Cursor uses the same shape in `.cursor/mcp.json`. On Windows, GUI hosts\ncannot always find `npx`, so use `\"command\": \"cmd\"` with\n`\"args\": [\"/c\", \"npx\", \"-y\", \"@nuver-labs/image-gen-mcp\"]`.\n\n## Use it\n\nJust ask, in plain language:\n\n- \"Generate a 16:9 hero image of a lighthouse at dusk and save it to `assets/hero.png`\"\n- \"Take `public/logo.png` and give it a transparent background\"\n- \"Create 3 variations of a flat paper airplane icon, square, into `design/drafts/`\"\n\nThe agent calls `generate_image` or `edit_image` with an absolute `output_path`\ninside your project, the file lands on disk, and the agent can then read the saved\npath to look at the result and refine it. If a call fails, ask it to run\n`list_capabilities` to see what is actually configured.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `generate_image` | Text prompt to one or more image files. Returns the absolute saved paths. |\n| `edit_image` | Edit or combine existing images with a text instruction. Never overwrites the sources. |\n| `list_capabilities` | Which providers are configured, default models, and the output directory rules. |\n\n### generate_image\n\n| Argument | Type | Notes |\n|---|---|---|\n| `prompt` | string, required | Subject, style, composition, colors, any text to render |\n| `output_path` | string | Absolute file path (.png/.jpg/.webp) or a directory. Given a directory, the filename is slugified from the prompt |\n| `provider` | `gemini` \\| `openai` | Overrides the default provider |\n| `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 |\n| `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| `n` | 1-4 | Gemini generates sequentially, so n>1 is slower there |\n| `quality` | `low` `medium` `high` `auto` | OpenAI only. `low` for cheap drafts |\n| `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 |\n| `image_size` | `1K` `2K` `4K` | Gemini 3.x only |\n| `return_image` | boolean | Also return the first image inline so the model can see it without a read. Costs context tokens |\n\n### edit_image\n\nEverything above, plus:\n\n| Argument | Type | Notes |\n|---|---|---|\n| `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 |\n| `input_fidelity` | `low` \\| `high` | OpenAI only. `high` preserves faces, logos, and fine detail. Ignored on gpt-image-2, which is always high fidelity |\n\nWhen `output_path` is omitted, the result is saved next to the first source image.\n\n### list_capabilities\n\nNo arguments. Reports configured providers as booleans (never key values), the\ndefault provider and models, known model options, the output directory fallback\nchain, and any directory restriction in force.\n\n## Configuration\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `GEMINI_API_KEY` | (unset) | Enables the Gemini provider |\n| `OPENAI_API_KEY` | (unset) | Enables the OpenAI provider |\n| `IMAGE_GEN_MCP_DEFAULT_PROVIDER` | key-based | `gemini` or `openai`. When unset: gemini if its key is set, else openai |\n| `IMAGE_GEN_MCP_GEMINI_MODEL` | `gemini-3.1-flash-image` | Default Gemini model |\n| `IMAGE_GEN_MCP_OPENAI_MODEL` | `gpt-image-2` | Default OpenAI model |\n| `IMAGE_GEN_MCP_OUTPUT_DIR` | (unset) | Fallback output directory when a call passes no `output_path` |\n| `IMAGE_GEN_MCP_ALLOWED_DIRS` | (unset) | Comma separated directories that all reads and writes are confined to. See [Security](#security) |\n| `IMAGE_GEN_MCP_TIMEOUT_MS` | `180000` | Per-request timeout to the provider API |\n| `IMAGE_GEN_MCP_LOG_FILE` | `~/.image-gen-mcp/images.jsonl` | JSONL ledger path. Absolute path to relocate, `none` to disable the file |\n\nWith no `output_path`, files go to the first of: `IMAGE_GEN_MCP_OUTPUT_DIR`,\n`CLAUDE_PROJECT_DIR` (set by Claude Code, points at the current project), the\nserver working directory.\n\n## Security\n\nThis server runs locally with your full user privileges and is not sandboxed by\nthe MCP client. Worth understanding before you grant it blanket tool approval.\n\n**What it can do.** Writes image files to disk. Reads the image files you point\n`edit_image` at. Sends your prompt, and any `edit_image` source image, to the\nprovider you selected. Makes billable API calls. That is the whole surface: three\ntools, no shell execution, no arbitrary URL fetching, no telemetry.\n\n**File access.** The model chooses `output_path` and `source_paths`, and by\ndefault they are unrestricted, because that is what makes the tool useful: your\nagent saves into whichever project you are working in. Note that Claude Code's\nworking-directory boundary does not extend to MCP servers, and Anthropic\n[does not security-audit third-party MCP servers](https://code.claude.com/docs/en/security).\n\nTo draw a hard boundary, set `IMAGE_GEN_MCP_ALLOWED_DIRS`:\n\n```bash\nIMAGE_GEN_MCP_ALLOWED_DIRS=/Users/you/projects,/Users/you/Desktop\n```\n\nEvery output path and every `edit_image` source must then resolve inside one of\nthose roots. Paths are compared after `realpath` resolution, so a symlink pointing\nout of a root is refused, and containment uses path segments rather than a string\nprefix, so a sibling directory like `/Users/you/projects-private` does not slip\nthrough. If none of the configured entries exist, the server refuses all file\naccess rather than silently running unrestricted.\n\n**API keys.** Keys are read only from the environment, passed to the provider SDK\nconstructors, and used nowhere else. They are never logged, never written to the\nledger, and never returned by `list_capabilities`, which reports booleans.\n\nThe risk is where you put them, not what this server does with them. Keys inlined\ninto `~/.claude.json` or `claude_desktop_config.json` sit in plaintext, readable by\nany process running as you, and an agent asked to read its own config can print\nthem into a transcript. Prefer exporting from a shell profile or a secret manager,\n`chmod 600` the config files, and use a dedicated key with a spend limit rather\nthan a shared production key.\n\n**Spend.** There is no built-in rate limit or cap. An agent in a retry loop can\ngenerate a lot of images quickly. Set\n[OpenAI hard spend limits](https://platform.openai.com/settings/organization/limits)\nand Google Cloud budget alerts.\n\n**Local log.** The ledger at `~/.image-gen-mcp/images.jsonl` contains a truncated\ncopy of each prompt in plaintext and grows without bound. Disable it with\n`IMAGE_GEN_MCP_LOG_FILE=none`, and do not commit it.\n\n**Prompt injection.** Tool results re-enter the model's context. Prefer per-call\napproval over blanket-allowing this server, and glance at the output path and any\n`edit_image` source path when approving. Pin a version and review the diff before\nupgrading.\n\nFound a vulnerability? See [SECURITY.md](https://github.com/nuver-labs/image-gen-mcp/blob/main/SECURITY.md). Please do not open a\npublic issue.\n\n## Logging\n\nEvery successful call records one structured JSON entry, two ways:\n\n- **stderr**, always: one `[image-gen-mcp] image {...}` line, visible in `/mcp`\n  output and Claude Code logs.\n- **JSONL ledger**, on by default: the same JSON appended to\n  `~/.image-gen-mcp/images.jsonl`, one line per call. Ledger write failures never\n  break a generation, they warn once on stderr.\n\nEach entry captures the provider, model, requested size, elapsed seconds, a\ntruncated prompt with its full character count, token usage when the provider\nreports it, and per-image details: saved path, byte size, human-readable size,\nmime type, and actual pixel dimensions.\n\n```bash\ntail -n 20 ~/.image-gen-mcp/images.jsonl\njq 'select(.usage) | .usage.totalTokens' ~/.image-gen-mcp/images.jsonl\n```\n\n## Costs\n\nEvery call hits a paid API, typically cents per image, varying by provider, model,\nquality, and size. Cheap options for drafts: OpenAI `quality: low` (roughly $0.006\nfor a low-quality 1024x1024 on gpt-image-2) or `gpt-image-1-mini`, and Gemini\n`gemini-3.1-flash-lite-image`. Gemini's `gemini-2.5-flash-image` may have a free\ntier on unbilled keys, so `IMAGE_GEN_MCP_GEMINI_MODEL=gemini-2.5-flash-image`\nmakes it the default.\n\n## Timeouts\n\nGeneration takes roughly 10 to 120 seconds depending on model and size. Claude\nCode's defaults are generous and this server sends progress notifications during\nlong calls, so no tuning is normally needed. If you set a tight global\n`MCP_TOOL_TIMEOUT`, add a per-server `\"timeout\": 600000` in `.mcp.json`.\n\n## Troubleshooting\n\n- Server logs go to stderr with an `[image-gen-mcp]` prefix. Claude Code surfaces\n  them in `/mcp` output and its logs.\n- **Registered but no tools**: start a new session, then check `claude mcp list`\n  and `claude mcp get image-gen`.\n- **`Provider 'x' is not configured`**: that key is missing from the MCP server\n  environment. Re-register with the `--env` flag or edit your config.\n- **Output is outside the allowed directories**: `IMAGE_GEN_MCP_ALLOWED_DIRS` is\n  set. Run `list_capabilities` to see the roots.\n- **Response too large**: `return_image` inlines a full image and can exceed the\n  MCP output token limit (`MAX_MCP_OUTPUT_TOKENS`, default 25k). Leave it off and\n  let the agent read the saved file.\n- **Gemini refusal**: the error includes the finish reason and any provider text.\n  Rephrase the prompt.\n\n## Build from source\n\nRequires Node 22+ and pnpm.\n\n```bash\ngit clone https://github.com/nuver-labs/image-gen-mcp.git\ncd image-gen-mcp\npnpm install\npnpm build\n```\n\nThen point your client at `node /abs/path/to/image-gen-mcp/dist/index.js` instead\nof `npx -y @nuver-labs/image-gen-mcp`.\n\n```bash\npnpm test      # unit tests, no API keys needed\npnpm inspect   # list the tools over real MCP stdio\n\n# Live tests. These cost real API credits.\nGEMINI_API_KEY=... node dist/smoke.js --provider gemini\nOPENAI_API_KEY=... node dist/smoke.js --provider openai\nnode dist/smoke.js --provider gemini --edit ./smoke-output/smoke-gen-gemini.png\n```\n\n## Contributing\n\nBug reports, provider quirk fixes, and documentation improvements are welcome.\nSee [CONTRIBUTING.md](https://github.com/nuver-labs/image-gen-mcp/blob/main/CONTRIBUTING.md). For anything larger, open an issue first.\n\nPlanned: OpenAI mask and inpainting support, migration off the legacy Gemini\n`generateContent` image path to the Interactions API, and more providers.\n\n## License\n\n[MIT](https://github.com/nuver-labs/image-gen-mcp/blob/main/LICENSE)\n\n---\n\nBuilt by [Nuver Labs](https://nuverlabs.com).\n",
  "bytes": 13454,
  "sha": "e52d2ba2993df23323fbf2d451c845ffe2d1f9590b120ac6ff36f88955964140",
  "repo_slug": "nuver-labs/image-gen-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_nuverlabs_image_gen_d604c475/readme"
}