image-generation-mcp

向你的代理要一张图片，它返回的是一个文件路径——而不是一整墙 base64。 服务器使用 Gemini 或 OpenAI 生成图片，写入磁盘，并且只返回绝对路径。 你的上下文窗口保持干净，文件就摆在那里，代理可以打开、移动或交给另一个工具。

功能

• 一个工具，无需繁琐流程。 generate_image(prompt, images, aspect_ratio)——这就是全部 API。

• 返回路径，而非负载。 返回绝对文件路径，因此一张 1.5 MB 的 PNG 只花你约 60 个 token，而不是约 200 万个。

• 两家提供商，自动选择。 设置你拥有的任意一个 API key。两个都设置了？由 IMAGE_PROVIDER 决定。

• 图生图。 最多传入 4 张参考图片，用于重塑风格、编辑或组合。

• 输入灵活。 参考图片可以是本地路径、http(s):// URL、data: URI 或裸 base64——服务器会自行判断。

• 两种传输方式。 本地客户端用 stdio，需要端口时用可流式 HTTP（仅绑定 localhost）。

• 诚实的错误。 不会用重试掩盖错误的 key，也不会静默回退提供商。当 API 返回 429，你看到的就是 429。

• 小到可以读完。 源码约 540 行，没有超过 100 行的文件，全程严格类型标注。

Related MCP server: VisionToolMCP

前置要求

计费说明。 两家提供商的图像模型都不属于免费层。未启用计费的 Gemini key 对每个图像模型都会返回 429 ... limit: 0。

快速开始

git clone https://github.com/farukcan/image-generation-mcp.git
cd image-generation-mcp
uv sync

cp .env.example .env      # add OPENAI_API_KEY or GEMINI_API_KEY
uv run pytest -m smoke    # generates a real image into out/

最后一条命令是端到端确认你的 key 是否可用的最快方式——它会打印刚刚生成的图片的路径。

添加到你的代理中

Claude Code

claude mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uvx --from git+https://github.com/farukcan/image-generation-mcp image-generation-mcp

uvx 会在首次运行时获取、构建并缓存该包——无需提前安装任何东西，也无需手动更新。

更喜欢一个可以编辑的检出副本？那就改为指向该目录：

claude mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uv run --directory /absolute/path/to/image-generation-mcp image-generation-mcp

添加 - s user 可让它在每个项目中可用，而不仅仅是当前项目。 用 claude mcplist 验证，用 claude mcp remove image-generation 移除。

Gemini CLI

相同的参数，相同的结构：

gemini mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uvx --from git+https://github.com/farukcan/image-generation-mcp image-generation-mcp

Cursor、Windsurf、Claude Desktop 以及其他一切

这些工具读取 JSON 配置文件（.cursor/mcp.json、claude_desktop_config.json、……）。 条目在所有地方都一样：

{
  "mcpServers": {
    "image-generation": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/farukcan/image-generation-mcp",
        "image-generation-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OUT_DIR": "/absolute/path/where/images/should/land"
      }
    }
  }
}

请为 GUI 客户端显式设置 OUT_DIR——它们启动时的工作目录往往不是你想的那个，out/ 会落在那里。

作为 HTTP 服务

uv run image-generation-mcp --transport http --port 8000

在 http://127.0.0.1:8000/mcp 上提供可流式 HTTP 端点。它只绑定到回环地址，且没有身份验证，因此暴露前要先放到代理后面。

工具

generate_image(prompt: str, images: list[str] | None = None, aspect_ratio: str = "1:1") -> str

返回写入文件的绝对路径，例如 /path/to/out/20260827-172746-c9b3.png。 文件名为 YYYYmdd-HMMSS-xxxx，因此结果按时间排序且永不冲突。

关于宽高比： Gemini 支持全部十种。OpenAI 只接受三种尺寸，因此比例会折叠到 1024x1024、1536x1024 或 1024x1536 中最接近的一个——在 OpenAI 上请求 16:9 得到的是 3:2。

配置

每个设置都是一个环境变量。工作目录（或任意父目录）中的 .env 文件会作为回退加载；真正的环境变量始终优先。

如果完全不带任何 API key 启动服务器，第一个请求就会大声失败，并指出它查找过的变量。

工作原理

flowchart LR
    A([MCP client]) -->|generate_image| B[server.py]
    B --> C[aspect.py<br/>validate ratio]
    B --> D[sources.py + download.py<br/>path / URL / base64 → bytes]
    B --> E{"registry.py<br/>which provider?"}
    E -->|GEMINI_API_KEY| F[gemini_provider.py<br/>Interactions API]
    E -->|OPENAI_API_KEY| G[openai_provider.py<br/>generate / edit]
    F --> H[output.py<br/>write into OUT_DIR]
    G --> H
    H -->|absolute path| A

每个模块只做一件事，且保持在 100 行以内。提供商按解析后的配置缓存，因此 SDK 客户端及其连接池会在多次调用间复用，而不是每个请求都重建。

提供商

有两个值得注意的刻意行为：

• Gemini 的图像 response_format 只接受显式 MIME 类型 image/jpeg，因此服务器不会请求该类型，而是根据返回的内容来命名文件。

• input_fidelity 从不会发送给 OpenAI——gpt-image-2 会用 400 拒绝它，然后自行应用高保真。

开发

uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest              # unit tests, all providers mocked
uv run pytest -m smoke -s  # real API calls; costs money, prints the paths

冒烟测试默认被排除，因此普通的 pytest 运行不会花钱。 test_edits_a_real_image 需要两次生成，因为它会制作自己的参考图片。

Logo 和截图也都是生成出来的——编辑脚本，而不是 SVGs：

uv run python media/generate_logo.py
uv run python media/generate_screenshot.py

每个文件 100 行的上限是刻意的设计约束，而不是偶然：它让每个模块都能在一屏内审阅。宁可拆分，也不要拉长。

故障排查

许可证

MIT © Ömer Faruk Can