Content
# 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:
```text
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
```bash
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
```bash
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`:
```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:
```toml
args = ["C:\\Users\\you\\eflowcode-image-mcp\\server.py"]
```
## Claude Desktop / Claude Code
Add this to your MCP config:
```json
{
"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:
```text
Generate a 16:9 research presentation cover about intelligent optimization algorithms and urban traffic.
```
Image edit:
```text
Edit C:\Pictures\apple.png so the apple becomes blue, keep the white background.
```
Multi-reference:
```text
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:
```text
用 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:
```bash
EFLOWCODE_GROK_BASE_URL=https://e-flowcode.cc/v1
EFLOWCODE_GROK_MODEL=<model listed by your E-FlowCode key>
```
## Response Handling
The server extracts base64 image data from `response.output` items where:
```json
{
"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](https://github.com/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。
服务默认调用：
```text
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 客户端环境变量读取
## 安装
```bash
git clone https://github.com/WenNinghan/eflowcode-image-mcp.git
cd eflowcode-image-mcp
python -m pip install -e .
```
安装后需要把 MCP 服务配置到你的客户端中。
## Codex 快速配置
```bash
python install.py --api-key sk-your-key --no-claude
```
执行后重启 Codex，然后让 Codex 调用 `server_info` 验证配置。
安装脚本会把 MCP 配置追加到 `~/.codex/config.toml`，并在写入前备份原配置。
## Codex 手动配置
把下面内容加入 `~/.codex/config.toml`：
```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 路径需要转义反斜杠：
```toml
args = ["C:\\Users\\you\\eflowcode-image-mcp\\server.py"]
```
## Claude Desktop / Claude Code 配置
在 MCP 配置中加入：
```json
{
"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 张输入图。
## 使用示例
文本生图：
```text
生成一张 16:9 的科研汇报封面图，主题是智能优化算法和城市交通。
```
单图编辑：
```text
把 C:\Pictures\apple.png 里的苹果改成蓝色，保持白色背景。
```
多图参考：
```text
参考这两张产品图，生成一张同风格的干净产品海报。
```
## Provider 路由
在 Codex 或其他 MCP 客户端里可以直接这样说：
```text
用 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 官方接口，请配置：
```bash
EFLOWCODE_GROK_BASE_URL=https://e-flowcode.cc/v1
EFLOWCODE_GROK_MODEL=<你的 E-FlowCode key 可用的模型名>
```
## 响应解析
服务会从 `response.output` 中提取如下结构里的 base64 图片：
```json
{
"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 成功 | 8-10 秒/张 | JPG，实际尺寸 784x1168 |
## 安全说明
- Provider API key 只会发送到对应 provider 的已配置 Base URL
- 工具运行时不接受动态 Base URL 参数，避免提示词注入导致 key 外泄
- 输出路径会被限制在 `EFLOWCODE_SAVE_DIR_ROOT` 下
- 上传前会校验输入图片的 magic bytes 和文件大小
- 写入本地前会限制生成图片的响应大小
- 示例文件只使用占位 key，不要提交真实 API key
## 贡献者
- [zuoliangyu](https://github.com/zuoliangyu)
## 许可证
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available