F
licenseA
qualityA
maintenanceWraps the Micu image API as an MCP server for generating, editing, batch processing, and multi-reference image fusion, supporting GPT-image-2 and Grok models.
5
86
-
gpt-image-mcp
by zK0G0w
This server provides local MCP tools for generating and editing images via OpenAI-compatible GPT Image APIs, saving results to local disk.
check_endpoint: Validates the configured API endpoint by requesting the model list; returns configuration status, endpoint availability, whether the model is listed, and HTTP status—without generating or editing images.
generate_image: Creates an image from a text prompt, with options for size, quality, format (png/jpeg/webp), background, moderation, and output compression; returns local path, file URI, MIME type, byte size, and dimensions.
edit_image: Edits images or creates new ones from 1–16 local reference images, supporting prompt, optional mask, size, quality, format, background, input fidelity, and output compression; saves a new file without overwriting originals.
Local file handling: All outputs are saved under the configured output directory with date-based subfolders, use unique filenames, and are returned as absolute filesystem paths and file:// URIs—not public URLs.
Configuration: Behavior is controlled via environment variables such as API key, base URL, model name, output directory, timeout, response format, and default size/quality.
Provides image generation and editing through the OpenAI GPT Image API, enabling text-to-image creation, image editing with masks and reference images, and saving generated images locally.
Click on "Install 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., "@gpt-image-mcpGenerate an image of a cozy cabin in snowy mountains at sunset."
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.
gpt-image-mcp
基于 TypeScript 的本地 stdio MCP 服务，调用 GPT Image 完成文生图、图片编辑和参考风格创作，图片保存在本机，返回绝对路径及文件 URI。
安装与配置
需要 Node.js 22 或更高版本，以及具有所选模型调用权限和可用额度的 OpenAI 或兼容服务商 API 密钥。支持 Linux、macOS 和 Windows。无需手动安装，通过 npx 自动下载运行。
MCP 配置（适用于 Claude Code、Claude Desktop、Cursor 等支持 MCP 的客户端）：
{
"mcpServers": {
"image-gen": {
"command": "npx",
"args": ["-y", "gpt-image-mcp"],
"env": {
"OPENAI_API_KEY": "你的 API 密钥",
"OPENAI_BASE_URL": "https://你的服务商/v1",
"IMAGE_GEN_MODEL": "服务商提供的图片模型名称",
"IMAGE_GEN_OUTPUT_DIR": "~/pictures"
}
}
}
}仅 OPENAI_API_KEY 必填，其余按需配置。详见下方配置章节。
首次启动会自动下载依赖，之后使用缓存。工具执行超时建议设为至少 360 秒；服务自身的 API 超时默认为 300 秒。
Related MCP server: gpt-image-2-mcp
配置
环境变量 | 默认值 | 说明 |
| 必填 | OpenAI API 密钥，通过客户端环境变量注入 |
|
| 未填写或留空时使用官方端点；仅填写域名时自动补 |
|
| 文生图和编辑共用的模型，允许兼容服务商的模型别名，需账号有权限 |
| 用户主目录下的 | 输出根目录，支持本机绝对路径或 |
|
| API 请求超时，单位毫秒，必须为不小于 1000 的整数 |
|
| API 返回图片的方式： |
|
| 全局默认分辨率，格式为 |
|
| 全局默认质量： |
OPENAI_BASE_URL 填写 API 根地址；未配置、空字符串或纯空格均使用官方端点。只有地址不包含路径时自动补 /v1，已有路径则按用户配置保留，避免破坏代理前缀或其他版本。尾部斜杠会去除，不会重复追加 /v1。
用户填写 | 实际使用的 API 根地址 |
不填 |
|
|
|
|
|
|
|
|
|
|
|
服务在根地址后追加 /images/generations、/images/edits 或 /models，不要填写完整生图接口地址。自定义路径如果需要 /v1，请明确填成 /proxy/v1。支持 HTTP 和 HTTPS，本地代理可用 http://localhost:8080；远程端点建议使用 HTTPS。地址不能包含账号密码、查询参数或 URL 片段。
Key、提示词和输入图片会发送到你配置的服务商。服务不会跟随 HTTP 重定向，请直接填写最终 API 根地址。
兼容服务商必须支持 OpenAI Image API 的 JSON 文生图、multipart 图片编辑，以及 data[].b64_json 或 data[].url 返回结构。服务会自动识别两种返回格式并正确处理。部分代理对新模型不支持 response_format 参数，保持 IMAGE_GEN_RESPONSE_FORMAT 默认值即可正常使用。仅兼容聊天接口或异步任务 ID 的服务不在当前兼容范围内。
端点检查与实际能力验证
服务启动时只校验本地配置，不自动联网探测或生成测试图片。需要检查时，在 MCP 客户端调用 check_endpoint，参数为 {}；也可以在配置好环境变量后运行：
gpt-image-mcp --check诊断最多等待 30 秒，不自动重试，只请求 GET /models，不会调用图片生成或编辑接口。结果说明：
字段 | 含义 |
|
|
|
|
| 当前模型是否出现在本次返回的列表中，无法确定时为 |
| 本项检查始终返回 |
| HTTP 状态码和说明，不回显密钥或上游原始错误消息 |
有些图片服务不提供 /models，或不会列出别名模型，所以检查失败和模型未列出都不会禁止生图。CLI 在模型列表正常时退出码为 0，其余情况为 1；退出码不代表图片能力通过或失败。
真正的兼容性验证需要分别执行一次 generate_image 和 edit_image，检查图片返回和落盘是否成功。这些调用可能计费，建议先使用 quality: "low"。文生图通过不能替代编辑接口测试，也不能保证所有参数组合均被服务商支持。
文件命名与路径
图片按 输出根目录/yyyy/MM/dd/文件名 保存，年月日取自实际保存时用户电脑的本地时间，月份和日期补齐两位，不采用 UTC 日期。跨天保存自动进入新目录。
文件名使用自建俏皮词表，组合“形容词 + 小动物 + 动作 + 奇妙事物 + 随机短码”，不额外调用语言模型取名：
cozy-otter-paints-moonlight-7d3a9b2c.png
sassy-capybara-juggles-marshmallows-c8e2a104.webp
dreamy-axolotl-brews-stardust-f0914abc.jpg默认路径示例：
Linux: /home/用户名/gpt-image-mcp/images/2026/09/10/cozy-otter-paints-moonlight-7d3a9b2c.png
macOS: /Users/用户名/gpt-image-mcp/images/2026/09/10/cozy-otter-paints-moonlight-7d3a9b2c.png
Windows: C:\Users\用户名\gpt-image-mcp\images\2026\09\10\cozy-otter-paints-moonlight-7d3a9b2c.png输出根目录保持固定，按日期归档；图片文件名使用 ASCII 小写字母、连字符和随机短码，避免系统保留字符与大小写差异。每次使用独占方式创建文件，名称碰撞会重新取名，绝不覆盖已有图片。支持中文和空格目录；uri 使用标准 URL 编码。旧版本生成的图片保留原位，不会自动迁移。
结果中的 path 是本机路径，uri 是 file:// URI，均不是公网下载地址。调用客户端必须能访问服务所在机器的文件系统；是否内联显示图片取决于客户端。图生图可以直接使用上一次返回的 path。
工具
generate_image
{
"prompt": "一只水獭在月光下画画，暖色手绘插画，柔和笔触",
"size": "1024x1024",
"quality": "medium",
"format": "png"
}edit_image
{
"prompt": "保留图一主体和构图，参考图二的配色与笔触，将背景改为雨夜街道",
"images": ["/绝对路径/原图.png", "/绝对路径/风格参考.webp"],
"quality": "high"
}局部编辑可增加 mask，填写本机遮罩路径。遮罩必须是含透明通道的 PNG，尺寸与第一张原图一致；完全透明区域表示希望编辑的部分。遮罩是模型的编辑指引，不保证像素级边界精确。
参数 | 默认值与范围 |
| 必填，去除首尾空白后 1～32000 字符 |
| 默认 |
| 默认 |
| 默认 |
| 默认 |
| 仅文生图，默认 |
| 可选 0～100 整数，仅 |
| 仅编辑，可选 |
| 编辑必填，1～16 张本机 PNG、JPEG 或 WebP；单图小于 50 MiB，参考图合计不超过 100 MiB |
| 编辑可选，本机 PNG 遮罩路径；单文件小于 50 MiB |
输入图片路径必须为本机绝对路径或以 ~/ 开头。每次生成一张新图片，不修改输入文件。
成功时同时返回 MCP 文本和 structuredContent，内容一致：
{
"images": [{
"path": "/Users/用户名/gpt-image-mcp/images/2026/09/10/cozy-otter-paints-moonlight-7d3a9b2c.png",
"uri": "file:///Users/%E7%94%A8%E6%88%B7%E5%90%8D/gpt-image-mcp/images/2026/09/10/cozy-otter-paints-moonlight-7d3a9b2c.png",
"mimeType": "image/png",
"bytes": 123456,
"width": 1024,
"height": 1024
}],
"model": "gpt-image-2.5-sunburst"
}失败返回 isError: true 和错误说明。服务关闭自动重试；超时或断线不代表上游没有执行，重新调用可能再次计费。图片生成成功但本地保存失败时会明确提示，不会重新调用生成接口。客户端取消会传递给 API 请求，但无法保证取消上游已开始的计费。
真实验收建议用 quality: "low" 各执行一次文生图和图生图，确认账号模型权限、网络、图片效果与客户端展示行为。
Available Tools
3 toolscheck_endpoint端点检查ARead-onlyIdempotent
请求当前端点的模型列表，检查响应格式和模型是否在列表中。不会发送生图或编辑请求；即使检查通过，图片能力仍需实际调用验证。
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| editing | Yes | |
| message | Yes | |
| generation | Yes | |
| httpStatus | Yes | |
| modelListed | Yes | |
| configuration | Yes | |
| modelsEndpoint | Yes |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds meaningful context beyond annotations by explicitly stating it sends no generation or editing requests and by warning that a passing check does not guarantee actual image capability. This is valuable behavioral nuance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The primary action and purpose come first, followed by the critical limitation. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter diagnostic tool with full annotations and an output schema, the description covers purpose, side-effect absence, and the key limitation. The agent has everything needed to invoke and interpret this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to clarify about parameter usage. The baseline of 4 applies because the description does not need to compensate for any schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: request the current endpoint's model list and check the response format and model presence. It also explicitly distinguishes itself from the sibling tools generate_image and edit_image by stating it will not send generation or editing requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when not to rely on this tool: even a successful check does not verify actual image capabilities, which require real invocation. It implies this tool is for endpoint/model-list validation, and the sibling names make the alternative clear, though it stops short of explicitly naming which sibling to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
edit_image编辑与参考创作A
读取本机图片，按提示词编辑、替换背景，或参考风格和构图生成新图。请明确各参考图的作用和需要保留的内容；可传遮罩引导局部编辑。保存新文件并返回绝对路径，不覆盖原图。调用会产生 API 费用。
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mask | No | 可选 PNG 遮罩的本机绝对路径，需含透明通道且尺寸与第一张原图一致；透明区域用于引导编辑。 | |
| size | No | 输出尺寸：auto 或 WIDTHxHEIGHT（如 1024x1024、1536x1024、3840x2160）。宽高需为 16 的倍数，比例不超过 3:1。 | auto |
| format | No | 保存的图片格式。 | png |
| images | Yes | 本机原图或参考图的绝对路径，可使用 ~/；按提示词引用的顺序排列。 | |
| prompt | Yes | 图片内容、风格、构图等要求。 | |
| quality | No | 生成质量，越高通常越慢且费用越高。 | auto |
| background | No | 背景模式；transparent 需配合 png 或 webp 格式。 | auto |
| input_fidelity | No | 编辑时对原图细节的保留程度，high 尽量保留原图主体。 | |
| output_compression | No | 输出压缩率（0-100），仅 jpeg 和 webp 格式生效。 |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| images | Yes |
TDQS
A4.5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses that it saves a new file and returns an absolute path without overwriting the original, and that the call incurs API costs. This adds meaningful behavioral context that annotations alone don't provide, and it doesn't contradict readOnlyHint=false or destructiveHint=false.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the core purpose and followed by invocation guidance, output behavior, and cost warning. No filler; each sentence adds distinct value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with an output schema, the description covers the critical operational facts: local input requirement, reference-image handling, mask support, non-destructive output, returned absolute path, and cost. The schema handles parameter details, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds useful guidance about clarifying each reference image's role and what to preserve, which maps to images/prompt, but doesn't add detail beyond the already-rich schema for mask, size, format, or quality.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: it reads local images, edits them per prompt, replaces backgrounds, or generates new images from reference style/composition. This clearly differentiates it from the generate_image sibling by requiring local image input and an edit/reference workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It lists concrete use cases (edit, background replacement, reference-based generation), instructs users to clarify each reference image's role and what to preserve, and notes when to pass a mask for local edits. It doesn't explicitly name alternatives or exclusions, but the local-image/edit framing makes the appropriate context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_image文生图A
根据提示词调用 GPT Image 生成一张图片，保存到本机并返回绝对路径和文件 URI。调用会产生 API 费用。
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | 输出尺寸：auto 或 WIDTHxHEIGHT（如 1024x1024、1536x1024、3840x2160）。宽高需为 16 的倍数，比例不超过 3:1。 | auto |
| format | No | 保存的图片格式。 | png |
| prompt | Yes | 图片内容、风格、构图等要求。 | |
| quality | No | 生成质量，越高通常越慢且费用越高。 | auto |
| background | No | 背景模式；transparent 需配合 png 或 webp 格式。 | auto |
| moderation | No | 内容安全审核级别。 | auto |
| output_compression | No | 输出压缩率（0-100），仅 jpeg 和 webp 格式生效。 |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| model | Yes | |
| images | Yes |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds concrete behavioral details beyond the annotations: it saves the image to local storage, returns an absolute path and file URI, and exposes that API costs are incurred. Annotations already indicate non-read-only and side-effecting behavior; the description enriches that with practical cost and persistence facts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence is front-loaded with the main action ('generate an image'), followed immediately by the return/side-effect behavior and the cost warning. It has no filler or duplication of schema information, and every character earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter tool with 100% schema coverage and a defined output schema, the description adds precisely the context that is not in structured data: persistence to local disk, the returned path/URI shape, and API fees. All the information an agent needs to call the tool correctly is covered by the description, schema, and annotations together.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 7 parameters already carry detailed semantic descriptions and enums. The description only repeats that the prompt drives generation, adding no new parameter meaning. The baseline of 3 is therefore correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action 'generate an image from GPT Image', the resource, and the deliverable: a local file with absolute path and file URI. It distinguishes itself from 'edit_image' (generating a new image vs modifying an existing one) and from 'check_endpoint', which is unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by contextually framing a text-to-image generation task. It does not explicitly state when to prefer this over edit_image or check_endpoint, and it provides no exclusion criteria or when-not-to-use guidance, leaving that inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.0- First observed
check_endpoint - First observed
edit_image - First observed
generate_image
TDQS
A4.4/5.0
Scored across 3 tools
Disambiguation5/5
Each tool has a clearly distinct purpose: check_endpoint validates API connectivity, generate_image creates new images, and edit_image modifies existing images. There is no meaningful overlap between these operations, so an agent can confidently select the right tool.
Naming Consistency5/5
All tool names follow the same verb_noun snake_case pattern: check_endpoint, generate_image, edit_image. This makes the tool set highly predictable and easy to reason about.
Tool Count5/5
Three tools is well-scoped for a focused GPT Image MCP server: endpoint validation, generation, and editing cover the core functionality without unnecessary bloat. Each tool earns its place.
Completeness4/5
The set covers the primary image lifecycle: checking endpoint availability, generating images, and editing existing images. Minor gaps exist, such as no explicit model listing or image variation/upscale capabilities, but the core workflows are complete enough for most use cases.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
Generate AI images and videos from any compatible MCP client.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
MCP server for Qwen Image 3 AI image generation
Related MCP Servers
- AlicenseAqualityBmaintenanceExposes OpenAI's gpt-image-2 (image generation and editing) as an MCP server for tools like generate_image, edit_image, and iterative edit sessions.62111MIT
- FlicenseAqualityDmaintenanceWraps Google Gemini's image generation API as an MCP server, enabling text-to-image, image editing, and grounded search workflows from any MCP client.2-
- AlicenseBqualityCmaintenanceA Model Context Protocol server that enables generating, editing, and multi-turn editing of images using OpenAI's gpt-image models directly from Claude or any MCP client.41MIT