Purpose
gen-image-mcp is a locally running MCP (Model Context Protocol) server designed to let you complete image generation and editing with a single sentence in MCP-compatible clients such as Claude Code, Cursor, and VS Code, and to have generated images land directly in the project directory so code can reference them immediately. The project is registered in the official MCP Registry.
Main Capabilities
- Images land directly in the project: images are saved on the machine running the MCP, so code can reference them right away.
- Use your own service and Key: supports any OpenAI-compatible Images interface (such as gpt-image-2, gpt-image-1.5, etc.), or Gemini image models (the Nano Banana series) provided through an OpenAI-compatible gateway. This project does not host any models.
- Automatic failover: on insufficient capacity or rate limiting, it first performs limited backoff retries, then switches to the next model in order.
- Full coverage of generation, reference images, and editing: supports text-to-image, reference-image generation, multi-image editing, and masks, returning inline previews and structuredContent.
Usage
The environment requirement is Node.js ≥ 20 (24 LTS recommended). You need to prepare: the service root URL (without /v1; the service automatically appends /v1/images/* and /v1/chat/completions), an API Key, and at least one set of models. The model names in the documentation are only examples; you must fill in the model IDs actually provided by your service provider. For the set you do not use, delete the corresponding variables rather than leaving empty strings.
Add --scope user in the configuration to use it across all projects. Note that the last --env must be separated from the service name by another parameter (such as --transport stdio).
- Cursor: after installation, replace the placeholder URL and Key with real values in
~/.cursor/mcp.json. - VS Code: after installation, a popup will ask you to enter the URL and Key.
- Clients that use mcpServers, such as Claude Desktop / Cline / Windsurf: fill them in according to their respective documentation.
- OpenCode: use the project's opencode.json or the global
~/.config/opencode/opencode.json; on Windows, change it to"command": ["cmd", "/c", "npx", "-y", "gen-image-mcp"].
Client field names differ:env or environment，command + args or a single command array,mcpServers or mcp / servers, please fill in according to the format in the client documentation. On native Windows environments, if the service fails to start (Connection closed, ENOENT), start npx through cmd, for example:
{"command": "cmd", "args": ["/c", "npx", "-y", "gen-image-mcp"]}
After restarting the client, you should see 4 tools. Then you can directly say: "Generate a 16:9 landing page header image and save it to public/hero.png."
Use Cases
Suitable for developers who need to quickly produce illustrations, header images, and assets in an IDE / coding assistant environment and write them directly into the project directory, as well as for users who want to use their own API service and Key and have autonomous control over the model provider.
Limitations
- Depends on the user-provided OpenAI-compatible interface or Gemini image model service and API Key; the project does not provide model hosting.
- Requires Node.js ≥ 20 (24 LTS recommended).
- Model names must be filled in with the IDs actually provided by the service provider; example names are not guaranteed to work.
- Licensed under MIT; this does not replace the upstream model service terms and does not determine the ownership of rights to generated images.
