gen-image MCP
This MCP server generates and edits images locally via OpenAI-compatible or Gemini image APIs, saving files directly to your project directory.
Generate images from text using the
generate_imagetool (OpenAI Images API, e.g., gpt-image-2), with options for size, quality, count (1–4), output format (png/jpeg/webp), and model selection.Edit or combine local images using the
edit_imagetool (OpenAI Images edits endpoint, multipart), accepting up to 16 input images and an optional mask, with size/quality/model options.Generate or edit images via Gemini models using
generate_gemini_image(chat completions endpoint), supporting text-to-image or reference-image generation, optional aspect ratios (e.g., 16:9, 1:1), and up to 16 input images.List configured models with
list_models— returns available models per API group (images/gemini), default model, associated tools, and global auto-fallback setting (no network request).Customizable output paths — save to files or directories; supports AI-provided filenames with automatic conflict avoidance (numbered suffixes), auto-creates parent directories.
Automatic model fallback — configurable retry and switch to next model on capacity/rate-limit errors (with backoff) or other upstream failures; can be overridden per call.
Rich result metadata — returns saved paths, previews (≤2 MiB), resource URIs, model used, elapsed time, attempt counts, and structured content for programmatic handling.
Local resource access — list and read generated images via MCP resources (
resources/list,resources/read), without size limits.Input validation — rejects invalid model names, oversized files (max 50 MiB each, 16 images), and invalid output paths before making upstream requests.
Generates and edits images through OpenAI-compatible image generation and editing APIs, with support for multiple models and local file output.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gen-image MCP Generate a red cube on a white desk with soft natural light and save it to exports/cube.png"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gen-image MCP
中文 | English
GitHub 项目:yuluo688/gen-image-mcp | 已登记 官方 MCP Registry
在 Claude Code、Cursor、VS Code 里一句话调用 GPT Image 或 Gemini(Nano Banana)生图、改图,图片直接存进项目目录;模型挂了自动切换到下一个。
为什么用它
图片直接落到项目里:保存在运行 MCP 的机器上,代码马上就能引用。
用自己的服务和 Key:任意 OpenAI 兼容的 Images 接口(
gpt-image-2、gpt-image-1.5等),或经 OpenAI 兼容网关提供的 Gemini 图像模型(Nano Banana 系列)。本项目不托管任何模型。失败自动切换:容量不足、限流先有限退避重试,再按顺序换下一个模型。
生图、参考图、改图全覆盖:文生图、参考图生成、多图编辑和蒙版,返回内联预览和
structuredContent。
Related MCP server: jgkme/kilo-image-gen-mcp
30 秒上手
需要 Node.js ≥ 20(推荐 24 LTS)。准备好 服务根地址(不带 /v1,服务会自动拼接 /v1/images/* 和 /v1/chat/completions)、API Key,以及至少一组模型。下面的模型名只是示例,请填写你的服务商实际提供的模型 ID;不用的那组请删掉对应变量,不要留空字符串。
Claude Code
claude mcp add --env GEN_IMAGE_BASE_URL=https://your-gateway.example \
--env GEN_IMAGE_API_KEY=your-api-key \
--env GEN_IMAGE_MODEL=gpt-image-2,gpt-image-1.5 \
--env GEN_IMAGE_GEMINI_MODEL=gemini-3.1-flash-image,gemini-2.5-flash-image \
--env GEN_IMAGE_AUTO_FALLBACK=true \
--transport stdio gen-image -- npx -y gen-image-mcp加 --scope user 可在所有项目中使用。注意最后一个 --env 和服务名之间要隔一个其他参数(如 --transport stdio)。
Cursor:
,安装后在
~/.cursor/mcp.json里把占位地址和 Key 换成真实值。VS Code:
(会弹窗让你输入地址和 Key)。
Claude Desktop / Cline / Windsurf 等使用 mcpServers 的客户端
{
"mcpServers": {
"gen-image": {
"command": "npx",
"args": ["-y", "gen-image-mcp"],
"env": {
"GEN_IMAGE_BASE_URL": "https://your-gateway.example",
"GEN_IMAGE_API_KEY": "your-api-key",
"GEN_IMAGE_MODEL": "gpt-image-2,gpt-image-1.5",
"GEN_IMAGE_GEMINI_MODEL": "gemini-3.1-flash-image,gemini-2.5-flash-image",
"GEN_IMAGE_AUTO_FALLBACK": "true"
}
}
}
}OpenCode(项目里的 opencode.json 或全局 ~/.config/opencode/opencode.json;Windows 上改为 "command": ["cmd", "/c", "npx", "-y", "gen-image-mcp"])
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"gen-image": {
"type": "local",
"command": ["npx", "-y", "gen-image-mcp"],
"enabled": true,
"environment": {
"GEN_IMAGE_BASE_URL": "https://your-gateway.example",
"GEN_IMAGE_API_KEY": "your-api-key",
"GEN_IMAGE_MODEL": "gpt-image-2,gpt-image-1.5",
"GEN_IMAGE_GEMINI_MODEL": "gemini-3.1-flash-image,gemini-2.5-flash-image",
"GEN_IMAGE_AUTO_FALLBACK": "true"
}
}
}
}各客户端字段名不同:
env还是environment,command+args还是单个command数组,mcpServers还是mcp/servers,请按你的客户端文档的格式填写。Windows 原生环境:如果服务起不来(Connection closed、ENOENT),请通过 cmd 启动 npx,例如"command": "cmd", "args": ["/c", "npx", "-y", "gen-image-mcp"]。
重启客户端,应能看到 4 个工具。然后直接说:“生成一张 16:9 的落地页头图,保存到 public/hero.png。”
工具一览
工具 | 用途 | 上游端点 |
| 文生图(尺寸、质量、1–4 张、png/jpeg/webp) |
|
| 编辑或合并 1–16 张本地图片,可加蒙版 |
|
| Gemini 文生图或参考图生成,支持 10 种宽高比 |
|
| 查看已配置的模型组和默认模型(不联网) | 无 |
详细文档
配置说明 · 模型选择、失败切换与重试 · 工具参数参考 · 文件、输出与 structuredContent · 常见问题 · 参与开发
许可证:MIT © 2026 yuluo688。不替代上游模型服务条款,也不约定生成图片的权利归属。
Available Tools
4 toolsedit_imageB
Edit or combine local images with POST /v1/images/edits (multipart). Use for gpt-image-2 image-to-image. Do not set input_fidelity for gpt-image-2.
Inputs: images (required), prompt (required), output_path (required), mask, +5 more.
generate_gemini_imageA
Generate or edit images with POST /v1/chat/completions using a Gemini image model. Do not call /v1/images/* for Gemini image models.
Inputs: prompt (required), output_path (required), model, images, +3 more.
generate_imageA
Generate images with POST /v1/images/generations (OpenAI Images API). Use for gpt-image-2 and other Images-only models. Do not send those models to chat completions.
Inputs: prompt (required), output_path (required), n, size, +5 more.
list_modelsARead-only
List configured model groups and the tools that use them. Returns configuration only — not live availability. Does not use network, credentials, or base URL.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool is tied to a specific API/model family: generate_image/edit_image for OpenAI image endpoints, generate_gemini_image for Gemini chat-completions, and list_models for configuration. There is slight functional overlap between generate_gemini_image and generate_image, but the usage rules make selection clear.
All tool names follow a consistent snake_case verb_noun pattern: list_models, generate_image, edit_image, generate_gemini_image. The model qualifier in generate_gemini_image is informative rather than inconsistent.
Four tools cover the core image generation and editing workflows plus model discovery. This is a well-scoped set with no redundant or filler tools.
The set covers generation and editing for both Gemini and OpenAI image models, plus model listing. Missing image variation functionality is a minor gap, but the main workflows have no dead ends.
Maintenance
Related MCP Connectors
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
MCP server for Qwen Image 3 AI image generation
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for Flux AI image generation
Related MCP Servers
- AlicenseBqualityDmaintenanceA local MCP server for generating and editing images using OpenAI-compatible APIs. It provides text-to-image generation and image editing capabilities with configurable endpoints and saves output directly to local files.225 npmMIT
- AlicenseNot gradedqualityCmaintenanceMCP server for generating, editing, and processing images via multiple providers including Kilo, OpenRouter, OpenAI, and Gemini, with local tools for background removal, resizing, and cropping.16 npm3MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server for AI-powered image processing (generate, edit, vary, analyze) supporting OpenAI, Gemini, Ideogram, and custom relay endpoints.-
- AlicenseAqualityDmaintenanceMCP server for AI image generation supporting text-to-image and image-to-image editing via any OpenAI-compatible service, with configurable models, aspect ratios, and sizes.2MIT