Eflowcode Image Mcp

EFLOWCODE Image MCP

MCP server for EFLOWCODE image generation across GPT Responses, Grok, and Nano Banana providers.

It exposes image tools to MCP clients such as Codex, Claude Desktop, Claude Code, Cursor, and other MCP-compatible agents. The default provider still calls:

POST {EFLOWCODE_BASE_URL}/responses
model: gpt-5.5
tools: [{"type": "image_generation"}]

You can also route a request with provider="grok" or provider="banana", or by choosing a model name such as grok-* or nano-banana-*. Existing calls that omit provider continue to use GPT Responses by default.

Features

• Text-to-image generation with image_generate
• Single image editing / reference generation with image_edit
• Batch image editing with image_batch_edit
• Multi-reference image synthesis with image_multi_reference
• Multi-provider routing with provider="gpt", provider="grok", or provider="banana"
• Automatic routing for grok-* and nano-banana-* model names
• Local file output with a save-directory sandbox
• Input image validation for PNG, JPEG, WebP, and GIF
• Works with EFLOWCODE or any compatible /v1/responses endpoint that supports image_generation
• Does not store API keys in this repository; keys are read from MCP client environment variables

Install

git clone https://github.com/WenNinghan/eflowcode-image-mcp.git
cd eflowcode-image-mcp
python -m pip install -e .

Then configure your MCP client.

Quick Setup For Codex

python install.py --api-key sk-your-key --no-claude

Restart Codex, then ask your agent to call server_info.

The installer appends this MCP server to ~/.codex/config.toml and backs up the existing config first.

Manual Codex Config

Add this to ~/.codex/config.toml:

[mcp_servers.eflowcode-image]
command = "python"
args = ["/absolute/path/to/eflowcode-image-mcp/server.py"]
env = {
  EFLOWCODE_API_KEY = "sk-your-key",
  EFLOWCODE_DEFAULT_PROVIDER = "gpt_responses",
  EFLOWCODE_BASE_URL = "https://e-flowcode.cc/v1",
  EFLOWCODE_MODEL = "gpt-5.5",
  EFLOWCODE_NANO_API_KEY = "sk-your-nano-key",
  EFLOWCODE_NANO_BASE_URL = "https://e-flowcode.cc",
  EFLOWCODE_NANO_MODEL = "nano-banana-pro",
  EFLOWCODE_GROK_API_KEY = "sk-your-grok-key",
  EFLOWCODE_GROK_BASE_URL = "https://api.x.ai/v1",
  EFLOWCODE_GROK_MODEL = "grok-imagine-image-quality",
  EFLOWCODE_SAVE_DIR = "~/Pictures/eflowcode-image-out",
  EFLOWCODE_SAVE_DIR_ROOT = "~/Pictures/eflowcode-image-out"
}

On Windows, use escaped paths:

args = ["C:\\Users\\you\\eflowcode-image-mcp\\server.py"]

Claude Desktop / Claude Code

Add this to your MCP config:

{
  "mcpServers": {
    "eflowcode-image": {
      "command": "python",
      "args": ["/absolute/path/to/eflowcode-image-mcp/server.py"],
      "env": {
        "EFLOWCODE_API_KEY": "sk-your-key",
        "EFLOWCODE_DEFAULT_PROVIDER": "gpt_responses",
        "EFLOWCODE_BASE_URL": "https://e-flowcode.cc/v1",
        "EFLOWCODE_MODEL": "gpt-5.5",
        "EFLOWCODE_NANO_API_KEY": "sk-your-nano-key",
        "EFLOWCODE_NANO_BASE_URL": "https://e-flowcode.cc",
        "EFLOWCODE_NANO_MODEL": "nano-banana-pro",
        "EFLOWCODE_GROK_API_KEY": "sk-your-grok-key",
        "EFLOWCODE_GROK_BASE_URL": "https://api.x.ai/v1",
        "EFLOWCODE_GROK_MODEL": "grok-imagine-image-quality",
        "EFLOWCODE_SAVE_DIR": "~/Pictures/eflowcode-image-out",
        "EFLOWCODE_SAVE_DIR_ROOT": "~/Pictures/eflowcode-image-out"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |---|---:|---|---| | EFLOWCODE_API_KEY | yes for GPT | - | GPT Responses API key used by provider=gpt | | EFLOWCODE_DEFAULT_PROVIDER | no | gpt_responses | Default provider when provider and model routing are absent | | EFLOWCODE_BASE_URL | no | https://e-flowcode.cc/v1 | GPT Responses base URL without trailing /responses | | EFLOWCODE_MODEL | no | gpt-5.5 | Responses model used for image generation | | EFLOWCODE_PROMPT_PREFIX | no | OpenAI no-rewrite prompt | Prefix added to GPT Responses prompts | | EFLOWCODE_NANO_API_KEY | yes for Banana | - | Nano Banana key used only by provider=banana | | EFLOWCODE_NANO_BASE_URL | no | https://e-flowcode.cc | Nano Banana base URL; generateContent path is appended automatically | | EFLOWCODE_NANO_MODEL | no | nano-banana-pro | Default Nano Banana model | | EFLOWCODE_GROK_API_KEY / XAI_API_KEY | yes for Grok | - | Grok/xAI key used only by provider=grok | | EFLOWCODE_GROK_BASE_URL | no | https://api.x.ai/v1 | Grok image API base URL. Use https://e-flowcode.cc/v1 when proxied by E-FlowCode | | EFLOWCODE_GROK_MODEL | no | grok-imagine-image-quality | Default Grok image model | | EFLOWCODE_HTTP_RETRIES | no | 2 | Retry count for retryable HTTP failures | | EFLOWCODE_REQUEST_TIMEOUT | no | 1200 | Request timeout in seconds | | EFLOWCODE_SAVE_DIR | no | ~/Pictures/eflowcode-image-out | Default output directory | | EFLOWCODE_SAVE_DIR_ROOT | no | same as save dir | Sandbox root for output paths | | EFLOWCODE_USE_SHELL_PROXY | no | 0 | Set to 1 to let httpx use shell proxy env vars |

Compatibility aliases are also accepted: EF_API_KEY, EF_BASE_URL, EF_MODEL, and OPENAI_API_KEY.

Tools

server_info

Returns current mode, base URL, model, save directory, and limits.

image_generate

Generate images from text.

Arguments:

• prompt: image prompt
• size: optional WxH, default 1024x1024
• n: number of images, 1-10
• model: optional override
• provider: optional gpt / grok / banana override
• aspect_ratio: optional provider aspect ratio such as 16:9 or 9:16
• image_size: optional Nano Banana size, 1K / 2K / 4K
• resolution: optional Grok resolution, 1k / 2k
• save_dir: optional output directory under EFLOWCODE_SAVE_DIR_ROOT
• basename: optional output filename stem

image_edit

Generate a new image using one local image as an input reference.

Arguments include prompt, image_path, optional size, model, provider, aspect_ratio, image_size, resolution, save_dir, and basename.

mask_path is accepted for interface compatibility. The current provider implementations do not upload alpha masks separately; describe the edit area in the prompt.

image_batch_edit

Apply the same edit prompt to multiple images, one request per image.

image_multi_reference

Generate one new image from 2-10 local reference images.

Grok multi-reference editing supports up to 3 input images.

Examples

Text-to-image:

Generate a 16:9 research presentation cover about intelligent optimization algorithms and urban traffic.

Image edit:

Edit C:\Pictures\apple.png so the apple becomes blue, keep the white background.

Multi-reference:

Use these two product images as references and generate one clean poster in the same style.

Provider Routing

You can keep prompts natural in MCP clients:

用 GPT 生图：a cinematic city skyline at dawn
用 Grok 生图：a product poster, 16:9
用 Banana 生图：一张 9:16 的柔和摄影风格人像
用 nano-banana-2-4k 生成 9:16 海报

Routing rules:

• Explicit provider wins. Aliases include gpt, openai, grok, xai, banana, nano, and nano-banana.
• Models starting with nano-banana route to Nano Banana automatically.
• Models starting with grok route to Grok automatically.
• Otherwise the server uses EFLOWCODE_DEFAULT_PROVIDER.

Provider Notes

• GPT uses /v1/responses with stream=true, tool_choice="required", and the no-rewrite prompt prefix.
• Nano Banana uses /v1beta/models/{model}:generateContent and reads images from structured inlineData.
• Grok text-to-image uses /v1/images/generations; Grok image editing uses JSON /v1/images/edits with image data URIs in image or images.

If your Grok access is proxied by E-FlowCode rather than xAI directly, set:

EFLOWCODE_GROK_BASE_URL=https://e-flowcode.cc/v1
EFLOWCODE_GROK_MODEL=

Response Handling

The server extracts base64 image data from response.output items where:

{
  "type": "image_generation_call",
  "result": "..."
}

If no image result is found, the tool returns a clear error plus a compact response summary.

Stability Smoke Test Results

The multi-provider generation path was smoke-tested with three text-to-image requests per provider, nine requests total:

| Provider | Model | Result | Typical latency | Output | |---|---|---:|---:|---| | Banana | nano-banana-pro | 3/3 successful | 21-23s/image | 1024x1024 JPG | | GPT | gpt-5.5 | 3/3 successful | ~20s/image | 1024x1024 PNG | | Grok | grok-imagine-image-lite | 3/3 successful | 8-10s/image | JPG, actual size 784x1168 |

Security Notes

• Provider API keys are only sent to their configured provider base URLs.
• Runtime tools do not accept a base URL parameter, to avoid prompt-injection key exfiltration.
• Output paths are restricted to EFLOWCODE_SAVE_DIR_ROOT.
• Input images are checked by magic bytes and size limits before upload.
• Generated binary responses are capped before writing to disk.
• Example files use placeholder keys only. Do not commit real API keys.

Contributors

• zuoliangyu

License

MIT

---

EFLOWCODE Image MCP 中文说明

这是一个面向 EFLOWCODE / Grok / Nano Banana 的多模型图像生成 MCP 服务。默认仍通过 Responses API 调用支持 image_generation 工具的 gpt-5.5 模型，也可以通过 provider="grok" 或 provider="banana" 路由到对应生图接口。不传 provider 的旧调用会继续走 GPT Responses。

服务默认调用：

POST {EFLOWCODE_BASE_URL}/responses
model: gpt-5.5
tools: [{"type": "image_generation"}]

GPT Responses 默认会在发送给模型前加上英文 no-rewrite 前缀，避免提示词被模型重写。

功能

• image_generate：文本生成图像
• image_edit：基于单张本地图片进行编辑或参考生成
• image_batch_edit：对多张图片逐张执行同一编辑指令
• image_multi_reference：使用 2-10 张参考图合成一张新图
• provider 路由：支持 gpt、grok、banana / nano-banana
• 模型名自动路由：grok-* 自动走 Grok，nano-banana-* 自动走 Banana
• 图片自动保存到本地目录
• 输出目录沙箱保护，避免写到非预期路径
• 输入图片格式和大小校验，支持 PNG、JPEG、WebP、GIF
• 可用于 EFLOWCODE 或任何兼容 /v1/responses 且支持 image_generation 的接口
• 仓库不会保存 API key；密钥从 MCP 客户端环境变量读取

安装

git clone https://github.com/WenNinghan/eflowcode-image-mcp.git
cd eflowcode-image-mcp
python -m pip install -e .

安装后需要把 MCP 服务配置到你的客户端中。

Codex 快速配置

python install.py --api-key sk-your-key --no-claude

执行后重启 Codex，然后让 Codex 调用 server_info 验证配置。

安装脚本会把 MCP 配置追加到 ~/.codex/config.toml，并在写入前备份原配置。

Codex 手动配置

把下面内容加入 ~/.codex/config.toml：

[mcp_servers.eflowcode-image]
command = "python"
args = ["/absolute/path/to/eflowcode-image-mcp/server.py"]
env = {
  EFLOWCODE_API_KEY = "sk-your-key",
  EFLOWCODE_DEFAULT_PROVIDER = "gpt_responses",
  EFLOWCODE_BASE_URL = "https://e-flowcode.cc/v1",
  EFLOWCODE_MODEL = "gpt-5.5",
  EFLOWCODE_NANO_API_KEY = "sk-your-nano-key",
  EFLOWCODE_NANO_BASE_URL = "https://e-flowcode.cc",
  EFLOWCODE_NANO_MODEL = "nano-banana-pro",
  EFLOWCODE_GROK_API_KEY = "sk-your-grok-key",
  EFLOWCODE_GROK_BASE_URL = "https://api.x.ai/v1",
  EFLOWCODE_GROK_MODEL = "grok-imagine-image-quality",
  EFLOWCODE_SAVE_DIR = "~/Pictures/eflowcode-image-out",
  EFLOWCODE_SAVE_DIR_ROOT = "~/Pictures/eflowcode-image-out"
}

Windows 路径需要转义反斜杠：

args = ["C:\\Users\\you\\eflowcode-image-mcp\\server.py"]

Claude Desktop / Claude Code 配置

在 MCP 配置中加入：

{
  "mcpServers": {
    "eflowcode-image": {
      "command": "python",
      "args": ["/absolute/path/to/eflowcode-image-mcp/server.py"],
      "env": {
        "EFLOWCODE_API_KEY": "sk-your-key",
        "EFLOWCODE_DEFAULT_PROVIDER": "gpt_responses",
        "EFLOWCODE_BASE_URL": "https://e-flowcode.cc/v1",
        "EFLOWCODE_MODEL": "gpt-5.5",
        "EFLOWCODE_NANO_API_KEY": "sk-your-nano-key",
        "EFLOWCODE_NANO_BASE_URL": "https://e-flowcode.cc",
        "EFLOWCODE_NANO_MODEL": "nano-banana-pro",
        "EFLOWCODE_GROK_API_KEY": "sk-your-grok-key",
        "EFLOWCODE_GROK_BASE_URL": "https://api.x.ai/v1",
        "EFLOWCODE_GROK_MODEL": "grok-imagine-image-quality",
        "EFLOWCODE_SAVE_DIR": "~/Pictures/eflowcode-image-out",
        "EFLOWCODE_SAVE_DIR_ROOT": "~/Pictures/eflowcode-image-out"
      }
    }
  }
}

环境变量

| 变量 | 是否必填 | 默认值 | 说明 | |---|---:|---|---| | EFLOWCODE_API_KEY | GPT 必填 | - | GPT Responses API key，仅供 provider=gpt 使用 | | EFLOWCODE_DEFAULT_PROVIDER | 否 | gpt_responses | 未指定 provider 时的默认生图 provider | | EFLOWCODE_BASE_URL | 否 | https://e-flowcode.cc/v1 | GPT Responses Base URL，不包含 /responses | | EFLOWCODE_MODEL | 否 | gpt-5.5 | 用于 Responses 图像生成的模型 | | EFLOWCODE_PROMPT_PREFIX | 否 | 英文 no-rewrite 前缀 | 自动添加到 GPT Responses 提示词前的前缀 | | EFLOWCODE_NANO_API_KEY | Banana 必填 | - | Nano Banana API key，仅供 provider=banana 使用 | | EFLOWCODE_NANO_BASE_URL | 否 | https://e-flowcode.cc | Nano Banana Base URL，服务会自动拼接 generateContent 路径 | | EFLOWCODE_NANO_MODEL | 否 | nano-banana-pro | 默认 Nano Banana 模型 | | EFLOWCODE_GROK_API_KEY / XAI_API_KEY | Grok 必填 | - | Grok/xAI API key，仅供 provider=grok 使用 | | EFLOWCODE_GROK_BASE_URL | 否 | https://api.x.ai/v1 | Grok 图片 API Base URL；走 E-FlowCode 代理时填 https://e-flowcode.cc/v1 | | EFLOWCODE_GROK_MODEL | 否 | grok-imagine-image-quality | 默认 Grok 图片模型 | | EFLOWCODE_HTTP_RETRIES | 否 | 2 | 可重试 HTTP 失败的重试次数 | | EFLOWCODE_REQUEST_TIMEOUT | 否 | 1200 | 请求超时时间，单位秒 | | EFLOWCODE_SAVE_DIR | 否 | ~/Pictures/eflowcode-image-out | 默认图片输出目录 | | EFLOWCODE_SAVE_DIR_ROOT | 否 | 同输出目录 | 输出目录沙箱根路径 | | EFLOWCODE_USE_SHELL_PROXY | 否 | 0 | 设为 1 时允许 httpx 使用系统代理环境变量 |

也兼容 EF_API_KEY、EF_BASE_URL、EF_MODEL 和 OPENAI_API_KEY。

工具说明

server_info

返回当前服务模式、Base URL、模型、保存目录和限制信息。

image_generate

根据文本生成图片。

常用参数：

• prompt：图片提示词
• size：可选，格式为 宽x高，默认 1024x1024
• n：生成数量，范围 1-10
• model：可选模型覆盖
• provider：可选 gpt / grok / banana
• aspect_ratio：可选比例，例如 16:9 或 9:16
• image_size：Nano Banana 可选尺寸，1K / 2K / 4K
• resolution：Grok 可选分辨率，1k / 2k
• save_dir：可选输出目录，必须位于 EFLOWCODE_SAVE_DIR_ROOT 下
• basename：可选文件名前缀

image_edit

使用一张本地图片作为输入参考，结合提示词生成新图。

常用参数包括 prompt、image_path、size、model、provider、aspect_ratio、image_size、resolution、save_dir 和 basename。

mask_path 参数会被保留用于接口兼容。当前 provider 实现不会单独上传 alpha mask。如果需要指定编辑区域，请直接在提示词中描述。

image_batch_edit

对多张图片逐张执行同一编辑提示词。每张图片会发起一次独立请求。

image_multi_reference

使用 2-10 张本地参考图生成一张新图。

Grok 多图参考编辑最多支持 3 张输入图。

使用示例

文本生图：

生成一张 16:9 的科研汇报封面图，主题是智能优化算法和城市交通。

单图编辑：

把 C:\Pictures\apple.png 里的苹果改成蓝色，保持白色背景。

多图参考：

参考这两张产品图，生成一张同风格的干净产品海报。

Provider 路由

在 Codex 或其他 MCP 客户端里可以直接这样说：

用 GPT 生图：a cinematic city skyline at dawn
用 Grok 生图：a product poster, 16:9
用 Banana 生图：一张 9:16 的柔和摄影风格人像
用 nano-banana-2-4k 生成 9:16 海报

路由规则：

• 显式 provider 优先，别名包括 gpt、openai、grok、xai、banana、nano、nano-banana。
• model 以 nano-banana 开头时自动走 Banana。
• model 以 grok 开头时自动走 Grok。
• 都没有指定时走 EFLOWCODE_DEFAULT_PROVIDER。

Provider 说明

• GPT 使用 /v1/responses，带 stream=true、tool_choice="required" 和 no-rewrite prompt 前缀。
• Nano Banana 使用 /v1beta/models/{model}:generateContent，从结构化 inlineData 读取图片。
• Grok 文生图使用 /v1/images/generations；Grok 图像编辑使用 JSON /v1/images/edits，图片以 data URI 放在 image 或 images 字段里。

如果你的 Grok 由 E-FlowCode 代理，而不是直接走 xAI 官方接口，请配置：

EFLOWCODE_GROK_BASE_URL=https://e-flowcode.cc/v1
EFLOWCODE_GROK_MODEL=

响应解析

服务会从 response.output 中提取如下结构里的 base64 图片：

{
  "type": "image_generation_call",
  "result": "..."
}

如果没有找到图片结果，工具会返回明确错误，并附带简短的响应摘要，方便排查接口兼容性。

稳定性 Smoke Test 结果

多 provider 生图链路已完成稳定性 smoke test：每个 provider 各执行 3 次文本生图，共 9 次请求，全部成功。

| Provider | 模型 | 结果 | 典型耗时 | 输出 | |---|---|---:|---:|---| | Banana | nano-banana-pro | 3/3 成功 | 21-23 秒/张 | 1024x1024 JPG | | GPT | gpt-5.5 | 3/3 成功 | 约 20 秒/张 | 1024x1024 PNG | | Grok | grok-imagine-image-lite | 3/3 成

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EF-FlowCode
• Source: EF-FlowCode/eflowcode-image-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.