MetaRouter Media MCP

把 MetaRouter 的生图接口和 HappyHorse 视频接口接入 Codex 或其他支持 MCP 的客户端。安装后，你可以直接用自然语言让 Codex 生成、编辑图片，也可以提交文生视频、图生视频、参考图生视频和视频编辑任务。

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

支持的工具

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

HappyHorse 支持 happyhorse-1.0-t2v、happyhorse-1.0-i2v、happyhorse-1.0-r2v 和 happyhorse-1.0-video-edit。除纯文生视频外，上游当前要求素材使用公网 HTTPS URL，不接受本地路径或 Base64。

Related MCP server: imagegen-mcp

快速安装到 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 的写实产品图：
白色摄影棚里悬浮着一台银色未来主义路由器，柔和轮廓光，高级商业摄影。

也可以直接说：

调用 video_generate，使用 happyhorse-1.0-t2v 生成 5 秒、720P、16:9 的视频：
澳门雨夜，一辆未来主义电动跑车驶过霓虹街道，电影级运镜。
提交后继续调用 video_status，wait=true，等待完成。

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 = 900

[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_VIDEO_MODEL = "happyhorse-1.0-t2v"
METAROUTER_SAVE_DIR = "C:/Users/you/Pictures/MetaRouter"
METAROUTER_SAVE_DIR_ROOT = "C:/Users/you/Pictures/MetaRouter"
METAROUTER_TRUSTED_VIDEO_HOSTS = "metarouters.org"

使用示例

文生图：

调用 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 可以继续读取、展示或交给后续流程处理。

文生视频：

调用 video_generate：
- model：happyhorse-1.0-t2v
- prompt：无人机穿越未来城市峡谷，日落金色逆光，连续电影镜头
- duration：5
- resolution：720P
- ratio：16:9

提交后把返回的 task_id 交给 video_status。设置 wait=true 可持续轮询，设置 download=true 可在完成后下载。图生视频使用 happyhorse-1.0-i2v 并传入一个 image_url；参考图生视频使用 happyhorse-1.0-r2v 并传入 1–9 个 reference_image_urls；视频编辑使用 happyhorse-1.0-video-edit 并传入 video_url。

若结果视频的域名不在信任列表中，先确认它确实属于 MetaRouter/上游视频 CDN，再把该域名加入 METAROUTER_TRUSTED_VIDEO_HOSTS 并重启 Codex。不要使用通配符。

环境变量

尺寸与计费提醒

• 尺寸格式是 宽x高，范围为 256–4096，宽和高都必须是 8 的倍数。

• image_batch_edit 会为每张输入图片分别发起一次接口调用，因此每张都会独立计费。

• image_multi_reference 会把多张参考图放进同一次编辑请求，是否支持以及具体限制取决于所选上游模型。

• HappyHorse 是异步任务：video_generate 只提交任务，实际完成情况使用 video_status 查询。

• video_status(wait=true) 最长等待 900 秒；超时不会取消任务，可稍后继续查询同一个 task_id。

• 视频时长目前为 3–15 秒，分辨率为 720P 或 1080P；具体可用组合以控制台为准。

• 最终可用模型、质量参数、速率限制和计费以 MetaRouter 控制台为准。

安全设计

• API 网关在代码中固定为 https://metarouters.org，MCP 参数不能覆盖它。

• 只接受 PNG、JPEG 和 WebP 本地输入，并限制单文件大小。

• 默认只能把生成结果写入 METAROUTER_SAVE_DIR_ROOT 内部。

• 远程结果只允许从 HTTPS 及受信任域名下载，减少 SSRF 风险。

• 视频 CDN 下载使用独立、无 Authorization 的客户端，不会把 MetaRouter API Key 发给结果域名。

• API 错误会截断和清理后再返回，不会主动输出 Authorization 请求头。

• API Key 保存在本机 Codex 配置中。不要把真实密钥写进仓库、截图、Issue 或日志；如已公开，请立即在控制台撤销并重新生成。

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

python install.py --reset

开发与测试

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

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

License

MIT