Skip to main content
Glama
eyaeya

relay-image-mcp

by eyaeya
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Relay Image MCP

本项目用于解决 Codex 接入中转站后，无法使用内置 OpenAI 图片生成模型 的场景。它通过独立的 MCP 图片工具调用显式配置的中转图片 API，让文生图和图片编辑可以继续在 Codex 中完成，并核对实际输出。

项目提供 stdio MCP 服务、独立命令行和可安装的 Agent Skill，也可用于其他支持 MCP 的客户端。它不会修改 Codex 内置工具的权限或账号套餐；能否使用指定模型，取决于中转站是否真正提供对应的图片接口与模型。已有文本对话可用，不代表图片接口也一定可用。

支持文字生成图片、文字加图片编辑、最多 5 张参考图，以及尺寸、比例、质量、背景和文件格式参数。返回的原图保持原始字节，检查结果会区分请求规格与实际结果。

适用范围

这个项目需要一个支持下列协议的图片服务：

  • 文生图：POST <base_url>/images/generations，JSON 请求体。

  • 带图请求：POST <base_url>/images/edits，图片以 images: [{"image_url": "data:image/png;base64,..."}] 放入 JSON 请求体。

  • 响应包含 b64_json 图片数据，支持 JSON 响应或完成事件形式的 SSE。

编辑接口使用 JSON 数据，不是通用的 multipart 上传接口。 仅支持 multipart 的服务不能直接使用。项目不会下载响应中的远程图片 URL，也不会自动改用其他协议、服务或模型。

支持 gpt-image-2、gpt-image-2.5-sunburst 和 gpt-image-2.5-flare，以及两个 Image-2.5 型号的 -2026-09-08 日期快照。这些标识与参数通过本地校验，不代表所配置服务一定提供对应模型或完整能力。

Image-2.5 支持与验证

官方当前提供 GPT Image 2.5 Sunburst 和 GPT Image 2.5 Flare。项目把选择的型号作为真实 JSON model 字段发送，不会在本地自动换成其他图片模型。

图片生成是否成功、平台记录的型号、响应中的型号标签，需要分开看。 2026-09-10 的测试中，Image-2.5 两个型号及其日期快照请求均成功返回可解码图片；随后核对的中转使用记录，将两个日期快照请求记录为对应的 Image-2.5 型号成功调用。

请求型号

图片结果

中转使用记录

API 响应标签

gpt-image-2.5-sunburst

成功返回图片

未单独对照

gpt-image-2-codex

gpt-image-2.5-flare

成功返回图片

未单独对照

gpt-image-2-codex

gpt-image-2.5-sunburst-2026-09-08

成功返回图片

对应 Image-2.5 型号成功调用

gpt-image-2-codex

gpt-image-2.5-flare-2026-09-08

成功返回图片

对应 Image-2.5 型号成功调用

gpt-image-2-codex

更正此前结论：不能仅凭 API 响应中的另一型号标签，断言中转未执行 Image-2.5。 平台记录与生成结果支持这两次日期型号请求调用成功。响应标签与平台记录的映射含义仍需服务提供者说明；平台记录和响应标签都不等于对内部实际执行模型的独立审计。公开说明不包含使用记录截图、账号、IP 或计费信息。

尺寸与参数另行验收：四次都请求 1024×1024、quality=low，实际图片均为 1254×1254，响应 quality=auto。这些差异仍成立，但不能用来否定模型调用成功；平台的分辨率或计费档位也不能替代对文件实际像素的检查。以上结果仅代表测试时的这一条接入。

工具使用 generation_status="succeeded" 表示已经收到并保存完整图片；delivery_status 单独表示请求规格的检查结果。未知或尚未建立映射的型号标签记为 unverified，不据此断言后台调用了错误模型。已知型号之间明确不同、或两个可识别回报互相矛盾时，才标记响应型号不符合；这仍只是回报一致性检查。

请求浮动别名后返回对应官方日期快照可视为回报匹配；请求特定日期快照却只返回浮动别名时，不能确认锁定了该版本。严格模式中的错误标记可能表示规格尚未验证或未满足，不等于图片生成请求失败。

Related MCP server: openai-imagegen-mcp

安装

需要 Python 3.11 或更新版本。运行依赖只有 Pillow；安装时自动获取。

从指定版本安装

建议使用独立虚拟环境：

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install "git+https://github.com/eyaeya/relay-image-mcp.git@v0.3.3"
.venv/bin/relay-image-mcp --help

此方式还需要 Git。Windows 的可执行文件位于 .venv\Scripts\，例如 .venv\Scripts\python.exe 和 .venv\Scripts\relay-image-mcp.exe。

从 Release 安装

从 v0.3.3 Release 下载 wheel，然后在虚拟环境中安装：

.venv/bin/python -m pip install /path/to/relay_image_mcp-0.3.3-py3-none-any.whl

Release 同时提供源码包及校验和文件。本项目尚未发布到 PyPI；不要使用不带来源的 pip install relay-image-mcp 代替以上安装方式。

配置服务

程序只读取显式指定的配置与环境变量，不会自动寻找其他应用的账号、登录状态或配置文件。

环境变量

在启动程序的进程环境中设置：

export IMAGE_RELAY_BASE_URL='https://relay.example/v1'
export IMAGE_RELAY_TOKEN='replace-with-your-provider-token'
.venv/bin/relay-image-mcp --status

示例域名与 token 均为占位内容。使用已有服务凭据即可，无需为本项目创建另一套凭据。桌面 MCP 客户端不一定继承终端变量，应按客户端的环境变量配置方式提供。

TOML 配置

创建自己的 settings.toml：

[provider]
base_url = "https://relay.example/v1"
env_key = "IMAGE_RELAY_TOKEN"

使用 --config /path/to/settings.toml 指定文件，也可设置 IMAGE_RELAY_CONFIG；命令行路径优先。若同时设置 IMAGE_RELAY_BASE_URL 或 IMAGE_RELAY_TOKEN，对应环境变量会覆盖文件中的地址或 token 来源。建议只在文件中引用环境变量，避免保存明文凭据。

如果服务需要自定义鉴权头，可改用：

[provider]
base_url = "https://relay.example/v1"

[provider.env_http_headers]
x-relay-authorization = "IMAGE_RELAY_AUTHORIZATION"

IMAGE_RELAY_AUTHORIZATION 的值应包含服务要求的完整头部值。也支持 [provider.http_headers] 直接配置头部，但其中的敏感值会成为本地文件中的明文。不要提交自己的配置文件。

远程服务要求 HTTPS；本地回环地址允许 HTTP。服务地址应包含实际 API 前缀，例如 /v1，不要附带 /images/generations。请求不跟随重定向。

在 Codex 中使用

先完成上方服务配置，再将虚拟环境中的可执行文件注册为 MCP：

codex mcp add relay_image -- /path/to/venv/bin/relay-image-mcp --config /path/to/settings.toml --output-dir /path/to/generated-images

也可以在 Codex 的 MCP 配置中手动添加：

[mcp_servers.relay_image]
command = "/path/to/venv/bin/relay-image-mcp"
args = ["--config", "/path/to/settings.toml", "--output-dir", "/path/to/generated-images"]
startup_timeout_sec = 20
tool_timeout_sec = 1200

使用已有中转站凭据，不需要为了这个项目再创建一把 OpenAI 官方 API key。凭据需要按上面的环境变量或 TOML 方式显式提供，程序不会自动读取其他应用的登录文件。重启该 MCP 服务后，可在 Codex 中请求“使用 relay_image 生成图片”或“修改这张图片”。Codex MCP 配置文档。

接入 MCP 客户端

在客户端的 MCP 配置中添加 stdio 服务。以下为常见配置结构，具体位置以客户端文档为准：

{
  "mcpServers": {
    "relay_image": {
      "command": "/path/to/venv/bin/relay-image-mcp",
      "args": [
        "--config", "/path/to/settings.toml",
        "--output-dir", "/path/to/generated-images"
      ]
    }
  }
}

将示例替换为实际绝对路径，确保客户端进程能读取配置和相应鉴权环境变量。Windows 可将 command 替换为虚拟环境中的 .exe 路径。保存后重新加载该 MCP 服务。

工具

作用

status

查看配置状态、参数范围与运行信息，不发起生图请求

inspect_image

只读检查本地图片的尺寸、格式、哈希与真实 Alpha

generate_image

生成或编辑一张图片，保存原图和技术检查报告

安装 Skill

.venv/bin/relay-image-mcp --install-skill /path/to/skills/relay-image

目标目录应是你的 Agent 支持的技能发现目录中的 relay-image 文件夹，且必须尚不存在；安装命令不会覆盖已有内容。该命令复制包内的 SKILL.md 和参数参考，不修改 MCP 配置，也不保存凭据。按客户端要求重新加载技能后，可直接提出文生图或改图需求，也可显式使用 $relay-image。

使用示例

文生图

.venv/bin/relay-image-mcp \
  --config /path/to/settings.toml \
  --output-dir /path/to/generated-images \
  --generate '清晨海边的一间木屋，写实摄影，柔和自然光' \
  --aspect-ratio 16:9 --size max --quality high

修改图片

.venv/bin/relay-image-mcp \
  --config /path/to/settings.toml \
  --generate '把杯子改成红色，保持杯子的形状、位置、构图和背景' \
  --reference-image /path/to/cup.png \
  --mode edit --size source --aspect-ratio source --strict

source 使用第一张参考图的原始像素尺寸或比例。如果尺寸超出支持范围，请选择合适的请求尺寸；程序不会静默缩放或裁切输入图。重复 --reference-image 可提供多张参考图；重复 --reference-roles 可逐项指定用途，重复 --preserve 可添加多项保留要求。

请求透明背景

.venv/bin/relay-image-mcp \
  --config /path/to/settings.toml \
  --generate '单独一株盆栽，透明背景，保留完整花盆和叶片' \
  --image-model gpt-image-2.5-sunburst \
  --background transparent --output-format png --strict

此示例要求服务实际支持该模型和透明输出。选择透明参数只代表发送了请求；最终以文件中的 Alpha 和检查结果为准。

MCP 参数示例

调用 generate_image：

{
  "prompt": "把第一张图里的杯子改成第二张图的红色，保留构图和背景",
  "reference_image_paths": ["/path/to/cup.png", "/path/to/color-reference.png"],
  "reference_roles": ["需要修改的杯子图片", "仅作为颜色参考"],
  "preserve": ["杯子形状与位置", "背景与构图"],
  "mode": "edit",
  "size": "2048x2048",
  "aspect_ratio": "1:1",
  "quality": "high",
  "background": "opaque",
  "output_format": "png",
  "strict": true
}

本地路径必须真实存在。preserve 和 reference_roles 会作为文字要求发送给服务，不能保证像素级不变。完整参数见 参数参考。

分辨率、质量与验收

默认使用 size="max"、quality="high"、image_model="gpt-image-2.5-sunburst" 和 PNG 输出。不传模型参数时直接请求 Sunburst，不需要在提示词中指定。使用不带日期的型号名称，保持该型号的浮动版本；不会自动改选未来其他名称的模型。明确传入其他受支持型号时仍按用户选择发送。没有参考图且未指定比例时，max 按正方形解析；有参考图时使用第一张图的比例。

max 会在当前适配器支持的范围内选择符合精确比例的最大画布：单边不超过 3840、总像素不超过 8,294,400、宽高均为 16 的倍数、比例介于 1:3 和 3:1。显式尺寸还要求不少于 655,360 像素。例如 16:9 的最大请求为 3840×2160，1:1 为 2880×2880。这些是请求限制，服务可能施加额外限制或返回不同尺寸。

质量与像素尺寸独立。gpt-image-2 接受 auto/low/medium/high；两个 gpt-image-2.5-* 标识还接受 xhigh/max。服务是否支持这些档位、是否真的使用指定模型，不能仅凭请求参数判断。

每次生成会检查实际图片的尺寸、比例、文件格式、Alpha 和哈希；服务回报的模型、质量等字段也会与请求区分呈现。精确尺寸必须一致，比例检查允许 1 像素的等效误差。透明检查要求存在真实非不透明像素，同时图片不能完全不可见。

strict=true 在可检查的规格未满足时返回错误状态，同时保留图片和检查报告；命令行此时以退出码 2 结束。模型或质量回报不一致也会被标记，缺失字段则标为未验证。严格模式不保证画面内容、人物身份、文字或编辑范围满足提示词，也不把服务自报的模型与质量当成独立证明。出现错误后不会自动重试、切换模型或降低参数。

原图不做放大、缩小、裁切、抠图或重新编码。若需要后处理，应另存处理结果，并与服务返回的原图区分。

文件与隐私

可用 --output-dir 指定保存目录。在 Unix 系统上，默认使用 $XDG_DATA_HOME/relay-image-mcp/images；未设置时使用 ~/.local/share/relay-image-mcp/images。Windows 默认使用 %LOCALAPPDATA%\relay-image-mcp\images。

  • 提示词和所选参考图片会发送给你配置的服务，包括为参考图添加的用途和保留要求。

  • 默认技术报告不保存提示词、参考图路径或服务改写的提示词，只保留参数、实际图片信息、哈希与检查结果等技术数据。

  • 原图保留服务返回的字节，也可能保留其中的 EXIF 或其他元数据。参考图按原始文件发送，因此也可能包含元数据。

  • 本地图片、技术报告以及 MCP 客户端记录仍可能包含敏感内容或路径；这不是匿名化工具。分享前应检查实际文件。

  • 程序不读取其他应用的账号；凭据由你显式提供。不要提交凭据；分享配置、生成结果或客户端日志前，应检查是否包含敏感内容。

开发与测试

git clone https://github.com/eyaeya/relay-image-mcp.git
cd relay-image-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/python -m unittest discover -s tests -v

测试使用本地数据与模拟服务，不需要远程凭据或付费生图。测试通过不代表某个远程服务支持全部参数。

许可证

MIT。版本记录见 CHANGELOG。

Available Tools

3 tools
generate_imageA

Generate or edit one image through the configured relay; send explicit output parameters and verify original returned bytes. No retries, resizing, model substitution or fallback.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoauto edits when references exist; generate uses references as inspiration. edit requires an input image.auto
sizeNomax, auto, source, or WIDTHxHEIGHT. Max resolves the largest documented legal request canvas. Returned dimensions are checked; no resampling.max
promptYes
strictNoReturn isError when requested constraints are unmet or model/quality metadata is insufficient; keep image and report.
qualityNoExplicit quality field. Higher levels require model support; returned metadata is checked separately from visual quality.high
preserveNoContent that must remain unchanged when editing; requires visual review.
backgroundNoauto, opaque or transparent. Real alpha pixels are inspected after full decoding.auto
image_modelNoExplicit image model; availability and supported quality depend on the provider. No automatic substitution.gpt-image-2.5-sunburst
aspect_ratioNoauto, source, or W:H e.g. 16:9, 9:16, 1:1. Must agree with explicit size. API derives a compatible size. Checked against actual output.auto
output_formatNoPNG, WebP or JPEG; transparent output requires PNG or WebP. Actual file format is verified.png
reference_rolesNoOne role per input image in order, e.g. edit target, lighting reference, object to insert.
reference_image_pathsNo

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds genuine behavioral claims beyond the annotations: no retries, no resizing, no model substitution, no fallback, and a requirement to verify the original returned bytes. Annotations already provide read-only, destructive, and idempotency hints, so these extra details meaningfully inform the agent without repeating structured data.

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, no waste: the first gives the core purpose, the second and third consolidate the critical behavioral contract. Every clause earns its place and it does not duplicate schema-defined parameter details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 parameters, no output schema, and annotations that already describe side effects, the description is enough to guide the agent at a high level, but does not fully cover what to know about the return value or when to prefer this tool over the sibling inspection/status tools. Overall, the main missing piece is selection routing, which is only a minor completeness gap.

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?

With 83% schema description coverage, the individual parameter descriptions already carry most of the semantic weight. The description provides a general instruction to set explicit output parameters and verify returned bytes, which touches several related properties but does not compensate for the few undocumented schema items (e.g., prompt, reference_image_paths).

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?

States the exact operation: 'generate or edit' the resource 'one image'. It is immediately distinct from the siblings inspect_image (inspection) and status (service state), so an agent can tell this tool apart without opening the schema.

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 intended purpose is implied clearly: use this when you need to generate or edit an image. However, there is no explicit when-to-use versus when-not-to-use guidance and the sibling tools are not referenced for comparison. The added constraints are about tool behavior, not selection strategy.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspect_imageA
Read-only

Fully decode a local image and report actual size, ratio, hash and alpha without modifying it.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, and the description reinforces this with 'without modifying it,' adding value by specifying what the tool reports (size, ratio, hash, alpha). Beyond that, it doesn't disclose potential failure modes or prerequisites, but the read-only safety profile is fully covered.

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, information-dense sentence with no filler. The core action and outputs are front-loaded, making the description immediately useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one simple parameter and a read-only operation, the description covers the action, outputs, and non-modifying behavior. Although return format and error conditions are not specified, the absence of an output schema and the simplicity of the task mean the description is nearly sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has a single 'path' parameter with no description, and the tool description also omits any explanation of the parameter. Although strong context clues (e.g., 'local image') imply path is the file location, the description provides no explicit semantics, leaving a gap given 0% schema coverage.

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 clear verb ('decode'), a specific resource ('local image'), and the exact outputs (size, ratio, hash, alpha). It is easily distinguishable from siblings: status (server state) and generate_image (creation), so an agent can select it without ambiguity.

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 for inspecting an existing local image and explicitly notes it does not modify the file. However, it does not mention when to prefer this tool over alternatives or when not to use it, leaving the decision to inference rather than explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

statusA
Read-only

Read local configuration readiness and capabilities; no network request.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true; the description adds 'no network request' as a meaningful behavioral trait beyond the annotation, confirming it is a safe, local read operation. No contradictions.

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, front-loaded sentence that states the purpose and the key non-network trait. Every word earns its place; no filler.

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 simple status-check tool with no parameters and no output schema, the description fully conveys what it does and its key characteristic. Nothing essential is missing.

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?

With zero parameters and 100% schema coverage (trivially), the description has no parameter burden. The baseline for 0 parameters is 4, and nothing in the description contradicts the schema.

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 verb ('Read') and resource ('local configuration readiness and capabilities'), clearly distinguishing it from the sibling image tools (inspect_image, generate_image). It is precise and unambiguous.

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 phrase 'no network request' conveys when this tool is appropriate (local-only checks) and implicitly differentiates it from any network-dependent alternatives. It lacks explicit when-not-to-use guidance, but the sibling context makes the usage clear.

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.

  1. 1 tool updatev0.3.3
    • Changedgenerate_image1 field changed
      • changedInput schema / properties / image_model / default
        Previous value: -"gpt-image-2"New value: +"gpt-image-2.5-sunburst"
  2. 3 tool updatesv0.3.2
    • First observedgenerate_image
    • First observedinspect_image
    • First observedstatus
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 3 tools

Disambiguation5/5

Each tool maps to a distinct operation: generating/editing an image, inspecting an existing local image, and checking server status. There is no functional overlap or plausible confusion between them.

Naming Consistency4/5

generate_image and inspect_image follow a clear verb_noun pattern, but status breaks that pattern by being a bare noun. The naming is otherwise consistent and predictable.

Tool Count5/5

Three tools is well-scoped for a small image relay server. Each tool covers a necessary, distinct responsibility without unnecessary bloat or missing basics.

Completeness5/5

The surface covers image generation/editing, local image inspection, and configuration readiness, which is complete for the stated relay purpose. No obvious dead ends or missing lifecycle operations for this narrow domain.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers