gen-image MCP

io.github.yuluo688Published by GitHub account yuluo688v0.2.3Updated Oct 24, 2026

Local stdio MCP for OpenAI-compatible and Gemini image generation, editing, and model fallback.

VerifiedSTDIODesktop onlyMedia & DesignAI & ML

Overview

AI-generated overview

Local MCP server that lets an assistant generate and edit images through an OpenAI-compatible or Gemini image API and save them into the project directory.

What you can do
Generate images from text prompts with configurable size, quality, count and format, saved to the project directory or returned inline with structured content. Edit or merge one to sixteen local images, optionally with a mask. Generate or reference-image images with Gemini image models across ten aspect ratios. List the configured model groups and defaults without network access. Retry with backoff and fall back to the next model when a model is rate-limited or out of capacity.
When to use it
Useful when you want an assistant inside Claude Code, Cursor, VS Code or a similar client to create or edit images and drop the files straight into the repository, using your own image API gateway and key rather than a hosted service.
Requirements
Runs locally over stdio via npx, so Node.js 20 or newer is needed (24 LTS recommended). Requires GEN_IMAGE_BASE_URL (service root without /v1), GEN_IMAGE_API_KEY, and at least one of GEN_IMAGE_MODEL or GEN_IMAGE_GEMINI_MODEL; optional GEN_IMAGE_AUTO_FALLBACK and GEN_IMAGE_TIMEOUT_MS. Network access to the configured gateway.
Before you install
The API key is passed in plain environment variables in client config files, so protect those files. Image generation calls the configured third-party gateway and may incur provider costs. The server writes generated images to the local machine, so check where files land. It does not host models and does not settle rights to generated images.

Installation

In SourceWeft

  1. Open gen-image MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

gen-image MCP

中文 | English

[npm version] [MCP Registry] [License: MIT]

GitHub 项目：yuluo688/gen-image-mcp | 已登记 官方 MCP Registry

在 Claude Code、Cursor、VS Code 里一句话调用 GPT Image 或 Gemini（Nano Banana）生图、改图，图片直接存进项目目录；模型挂了自动切换到下一个。

[gen-image MCP 演示：在 Claude Code 中一句话生成图片并保存到项目]

为什么用它

  • 图片直接落到项目里：保存在运行 MCP 的机器上，代码马上就能引用。
  • 用自己的服务和 Key：任意 OpenAI 兼容的 Images 接口（gpt-image-2、gpt-image-1.5 等），或经 OpenAI 兼容网关提供的 Gemini 图像模型（Nano Banana 系列）。本项目不托管任何模型。
  • 失败自动切换：容量不足、限流先有限退避重试，再按顺序换下一个模型。
  • 生图、参考图、改图全覆盖：文生图、参考图生成、多图编辑和蒙版，返回内联预览和 structuredContent。

30 秒上手

需要 Node.js ≥ 20（推荐 24 LTS）。准备好 服务根地址（不带 /v1，服务会自动拼接 /v1/images/* 和 /v1/chat/completions）、API Key，以及至少一组模型。下面的模型名只是示例，请填写你的服务商实际提供的模型 ID；不用的那组请删掉对应变量，不要留空字符串。

Claude Code

bash
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）。

Claude Desktop / Cline / Windsurf 等使用 mcpServers 的客户端

json
{  "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"]）

json
{  "$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。”

工具一览

工具用途上游端点
generate_image文生图（尺寸、质量、1–4 张、png/jpeg/webp）POST /v1/images/generations
edit_image编辑或合并 1–16 张本地图片，可加蒙版POST /v1/images/edits
generate_gemini_imageGemini 文生图或参考图生成，支持 10 种宽高比POST /v1/chat/completions
list_models查看已配置的模型组和默认模型（不联网）无

详细文档

配置说明 · 模型选择、失败切换与重试 · 工具参数参考 · 文件、输出与 structuredContent · 常见问题 · 参与开发

许可证：MIT © 2026 yuluo688。不替代上游模型服务条款，也不约定生成图片的权利归属。

Source: README.md at commit 64db8ff

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.2.3LatestOct 10, 2026
  2. v0.2.2Sep 21, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts