内容
# 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.
## 功能
- `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 .
```
## Codex 快速配置
```bash
python install.py --api-key sk-your-key --no-claude
```
## 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"
}
```
## 环境变量
| 变量 | 是否必填 | 默认值 | 说明 |
|---|---:|---|---|
| `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 使用系统代理环境变量 |
## 工具说明
### `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`。
### `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 使用 `/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` 字段里。
## 响应解析
服务会从 `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
