MetaRouter Image MCP

把 MetaRouter 的 OpenAI 兼容生图接口接入 Codex 或其他支持 MCP 的客户端。安装后，你可以直接用自然语言让 Codex 生成图片、编辑本地图片、批量编辑，或使用多张参考图合成新图。

这个项目从零实现，服务地址固定为 https://metarouters.org，不会把 API Key 发送到用户指定的第三方地址。

支持的工具

MCP 工具	用途
image_generate	文生图，一次生成 1–4 张图片
image_edit	根据提示词编辑一张本地图片
image_batch_edit	对多张本地图片逐张执行同一种编辑
image_multi_reference	以 2–10 张图片作为同一次生成的参考图
server_info	查看当前模型、保存目录和安全设置，不返回密钥

默认模型是 gpt-image-2。当尺寸达到约 4K 时会自动选择 gpt-image-2-pro，也可以在调用时显式指定模型。

快速安装到 Codex

要求：

• Python 3.10 或更高版本
• 已安装 Codex 桌面端或 Codex CLI
• 一个可用的 MetaRouter API Key

克隆仓库并运行安装器：

git clone https://github.com/cimicimi9090/mcp-pic-metarouters.git
cd mcp-pic-metarouters
python install.py

安装器会：

1. 隐藏输入 API Key；
2. 调用 https://metarouters.org/v1/models 验证密钥及生图模型；
3. 安装 Python 依赖；
4. 备份并更新 ~/.codex/config.toml；
5. 将图片默认保存到 ~/Pictures/MetaRouter。

安装完成后重启 Codex。先尝试：

调用 metarouter-image 的 server_info

然后可以直接说：

调用 image_generate，生成一张 1536x1024 的写实产品图：
白色摄影棚里悬浮着一台银色未来主义路由器，柔和轮廓光，高级商业摄影。

Codex 手动配置

不使用安装器时，可以先安装当前项目：

python -m pip install -e .

然后在 ~/.codex/config.toml 中添加以下配置。请把路径和密钥替换为你自己的值：

[mcp_servers.metarouter-image]
command = "C:/Path/To/python.exe"
args = ["D:/Path/To/mcp-pic-metarouters/server.py"]
startup_timeout_sec = 30
tool_timeout_sec = 360

[mcp_servers.metarouter-image.env]
METAROUTER_API_KEY = "sk-your-metarouter-key"
METAROUTER_IMAGE_MODEL = "gpt-image-2"
METAROUTER_IMAGE_PRO_MODEL = "gpt-image-2-pro"
METAROUTER_SAVE_DIR = "C:/Users/you/Pictures/MetaRouter"
METAROUTER_SAVE_DIR_ROOT = "C:/Users/you/Pictures/MetaRouter"

使用示例

文生图：

调用 image_generate：
- prompt：一张极简蓝紫渐变的 SaaS 产品封面，中心是抽象字母 M，干净留白
- size：1024x1024
- n：1

编辑本地图片：

调用 image_edit：
- image_path：C:/Users/you/Pictures/source.png
- prompt：保留主体构图，把背景改成夜晚的东京街头，增加自然霓虹反光
- size：1536x1024

多参考图：

调用 image_multi_reference：
- image_paths：两到十张本地 PNG、JPEG 或 WebP 文件
- prompt：使用第一张的构图、第二张的配色和第三张的材质，生成统一的新设计
- size：2048x2048

工具返回生成文件的绝对路径，Codex 可以继续读取、展示或交给后续流程处理。

环境变量

变量	默认值	说明
METAROUTER_API_KEY	无	必填，MetaRouter API Key
METAROUTER_IMAGE_MODEL	gpt-image-2	常规生图模型
METAROUTER_IMAGE_PRO_MODEL	gpt-image-2-pro	大尺寸自动使用的模型
METAROUTER_TIMEOUT	300	请求超时秒数，最小 30 秒
METAROUTER_SAVE_DIR_ROOT	~/Pictures/MetaRouter	MCP 允许写入的根目录
METAROUTER_SAVE_DIR	与根目录相同	默认输出目录，必须位于根目录内
METAROUTER_INPUT_ROOT	不限制	可选；设置后只允许读取该目录内的参考图片
METAROUTER_MAX_INPUT_MB	10	单张本地输入图片的大小上限
METAROUTER_TRUSTED_IMAGE_HOSTS	metarouters.org	允许下载结果图片的 HTTPS 域名，逗号分隔

尺寸与计费提醒

• 尺寸格式是 宽x高，范围为 256–4096，宽和高都必须是 8 的倍数。
• image_batch_edit 会为每张输入图片分别发起一次接口调用，因此每张都会独立计费。
• image_multi_reference 会把多张参考图放进同一次编辑请求，是否支持以及具体限制取决于所选上游模型。
• 最终可用模型、质量参数、速率限制和计费以 MetaRouter 控制台为准。

安全设计

• API 网关在代码中固定为 https://metarouters.org，MCP 参数不能覆盖它。
• 只接受 PNG、JPEG 和 WebP 本地输入，并限制单文件大小。
• 默认只能把生成结果写入 METAROUTER_SAVE_DIR_ROOT 内部。
• 远程结果只允许从 HTTPS 及受信任域名下载，减少 SSRF 风险。
• API 错误会截断和清理后再返回，不会主动输出 Authorization 请求头。
• API Key 保存在本机 Codex 配置中。不要把真实密钥写进仓库、截图、Issue 或日志；如已公开，请立即在控制台撤销并重新生成。

卸载由安装器写入的 Codex 配置：

python install.py --reset

开发与测试

python -m pip install -e ".[dev]"
python -m pytest

测试不需要真实 API Key，也不会发起计费请求。

License

MIT