Image Gen

What the Image Gen MCP server does

Image Gen MCP server connects an MCP-compatible coding agent to Google Gemini image models and OpenAI GPT image models. It accepts natural-language prompts for new images, saves the results as PNG, JPEG, or WebP files, and returns absolute paths to those files. It can also modify an existing image or combine multiple source images without overwriting the originals.

The package supports one configured provider or both. A capability query reports which providers are available, the configured defaults, known model choices, output-directory behavior, and any active directory restriction. Provider API calls are billable and use the keys supplied through the environment.

How it works

The agent calls generate_image with a prompt and optional output path, provider, model, aspect ratio, number of results, quality, background, image size, or inline-return settings. An output path may identify a file or directory. When a directory is supplied, the filename is derived from the prompt. If no path is provided, the server checks its configured output directory, the Claude Code project directory, and then its working directory.

edit_image accepts one to 16 absolute source paths. The first image is the edit target and the remaining files act as references. It supports the generation options plus provider-specific fidelity controls. If no output path is given, the result is placed beside the first source image. Generated files remain available for the agent to inspect and refine.

The Image Gen MCP server runs as an MCP process started with npx -y @nuver-labs/image-gen-mcp. Its tools perform file reads and writes and send prompts or selected source images to the chosen provider. It does not provide shell execution or arbitrary URL fetching.

Setup and configuration

At least one provider key is required: GEMINI_API_KEY enables Gemini and OPENAI_API_KEY enables OpenAI. The default provider is Gemini when its key is present; otherwise OpenAI is selected. You can override provider defaults with IMAGE_GEN_MCP_DEFAULT_PROVIDER, IMAGE_GEN_MCP_GEMINI_MODEL, and IMAGE_GEN_MCP_OPENAI_MODEL.

Additional settings include IMAGE_GEN_MCP_OUTPUT_DIR for fallback files, IMAGE_GEN_MCP_ALLOWED_DIRS for restricting reads and writes, IMAGE_GEN_MCP_TIMEOUT_MS for provider request limits, and IMAGE_GEN_MCP_LOG_FILE for the JSONL activity ledger. Set the ledger variable to none to disable that file. API keys are read from the environment and are not returned by list_capabilities.

Claude Code can add the server with claude mcp add; Claude Desktop and Cursor use an MCP JSON configuration with npx as the command. On Windows, GUI hosts may need cmd /c npx -y @nuver-labs/image-gen-mcp instead.

Tools and capabilities

• generate_image: Create one to four images from a text prompt.
• edit_image: Edit or combine existing PNG, JPEG, or WebP files without replacing source files.
• list_capabilities: Inspect configured providers, model defaults, model options, output fallback rules, and directory restrictions.

Gemini supports the listed Gemini image models and 1K, 2K, or 4K output on Gemini 3.x. OpenAI supports quality and background controls, with transparent backgrounds available through supported models. Aspect ratios include square, portrait, landscape, and wider formats; exact behavior varies by provider and model.

Limitations and notes

The server operates locally with the user’s privileges and is not sandboxed by the MCP client. Unless IMAGE_GEN_MCP_ALLOWED_DIRS is configured, paths selected for output and editing are unrestricted. With that setting, every path must resolve inside an allowed directory; invalid or nonexistent roots cause file access to be refused.

Gemini generates multiple requested images sequentially, so larger n values take longer. The return_image option places the first result in the model context and consumes context tokens. OpenAI-only and Gemini-only options are ignored or adjusted when an incompatible model is selected. The Image Gen MCP server sends prompts and edit source images to the selected provider, so avoid supplying material that should not leave the local environment.