gpt-image-mcp

**赋予 Claude Code 图像生成的超能力。**说一句“帮我画张图”，Claude Code 就会在对话中直接使用 OpenAI gpt-image-2 生成图像——无需切换应用，也无需复制提示词。

🎯 这是什么？

面向 Claude Code 用户： 该项目将 gpt-image-2 图像生成直接接入 Claude Code，作为 MCP 服务器。只需安装一次、注册一次，Claude Code 便获得原生的 generate_image 能力——你用自然语言（任何语言）描述图像，Claude Code 会生成提示词、调用 gpt-image-2，并把本地生成的 PNG 交给你。如果你一直希望 Claude 能“直接画出来”而不是解释，这就是那块缺失的拼图。

它也可以作为独立 CLI 使用，并可接入任何其他 MCP 主机——同一套核心，处处可用。

无需 ChatGPT Plus 订阅——只需任意一个支持 gpt-image-2 的 API 密钥。

工作流程：

You: "A cyberpunk orange tabby cat in a spacesuit, starfield, cinematic lighting"
  ↓  Claude Code optimizes your prompt into professional English (automatic)
  ↓  gpt-image-mcp calls OpenAI gpt-image-2
  ↓  PNG saved locally → absolute path returned
You: got your image ✓

Related MCP server: gpt-image-mcp

✨ 功能特性

• **原生 Claude Code 集成。**注册一次，Claude Code 就拥有真正的 generate_image 工具——用自然语言描述任何场景，即可在对话中拿到本地生成的 PNG。

• **两个入口，同一核心。**同一套生成逻辑同时支持 MCP 服务器和纯 CLI。

  • gpt-image-mcp --mcp → 提供 generate_image / list_images 工具的 stdio MCP 服务器

  • gpt-image-mcp "a cat in a spacesuit" → 一次性 CLI 生成

• 兼容任意 OpenAI 后端。 将 OPENAI_BASE_URL 指向任意你喜欢的位置（经销商、代理、自托管网关）。

• 质量档位 对应 gpt-image-2 自带的 low / medium / high 旋钮。没有额外模型，也没有额外费用惊喜。

• 密钥永不写入代码。 完全通过环境变量驱动——机密信息不会进入你的仓库。

• 异步安全。 图像以 base64 解码后的 PNG 形式流式写入本地磁盘；API 永远不会替你写盘。

🧰 环境要求

• Python 3.10+

• 一个 OpenAI API 密钥，或一个提供 gpt-image-2（或通过 GPT_IMAGE_MODEL 设置的其他兼容模型）的 OpenAI 兼容端点（经销商 / 网关 / 自托管）。

• 可通过 pip 或 uv 安装的 Python。

📦 安装

从 PyPI 安装

pip install gpt-image-mcp           # pip
# or
uv tool install gpt-image-mcp       # uv

从源码安装

git clone https://github.com/Garfield-Wuu/gpt-image-mcp
cd gpt-image-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e .

⚙️ 配置

所有配置均通过环境变量完成：

提示： 默认基础 URL 是 OpenAI 官方端点。要使用经销商或代理，只需将 OPENAI_BASE_URL 设置为它的 /v1 根路径——其他一切都不用改。

🚀 使用

作为 MCP 服务器（Claude Code）

注册服务器（将 ~/.venv 替换为你的实际环境路径）：

claude mcp add gpt-image -s user \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env OPENAI_BASE_URL="$OPENAI_BASE_URL" \
  --env GPT_IMAGE_OUT="$PWD/out" \
  -- gpt-image-mcp --mcp

重启 Claude Code 后，两个工具即会可用：

• generate_image — 生成图像并保存到本地。

  ┌─────────────────────────────────────────────────────────────┐
  │ "A cyberpunk orange tabby cat in a spacesuit …"             │
  │    → gpt-image-mcp → local PNG → absolute path returned    │
  └─────────────────────────────────────────────────────────────┘

  参数：prompt（必填）、size、quality、out_name。

• list_images — 列出之前生成的 PNG（最新的在前）。

在 Claude Code 中怎么说：

“画一只穿着宇航服的赛博朋克橘猫，星空背景，电影感，高质量。” → 触发 generate_image

“生成一张 1536x1024 横向英雄图：雨中的赛博朋克城市，霓虹倒影。” → 设置尺寸 + 质量

“我以前生成过哪些图像？” → 触发 list_images

无需任何魔法语法——只需用你自己的话、以任何语言描述图像即可。其余交给 Claude Code。

作为 CLI

export OPENAI_API_KEY="sk-..."
gpt-image-mcp "a cyberpunk orange tabby cat, neon rain, cinematic" \
  --size 1536x1024 --quality high --out ./out/hero.png

在没有 --no-interactive 的情况下，当存在 TTY 时，CLI 会以交互方式让你选择尺寸/质量。

🖼️ 参数

size — 画布方向：

quality — gpt-image-2 自身的质量旋钮（单一模型；取舍在于速度/成本与细节之间的平衡）：

🛠️ 开发

pip install -e ".[dev]"
ruff check .            # lint
pytest                  # run tests
python -m build         # build sdist + wheel

目录结构：

src/gpt_image_mcp/
├── img_core.py    # shared generation logic (no MCP dependency)
├── mcp_server.py  # FastMCP server: generate_image / list_images
└── __main__.py    # CLI + MCP entrypoints

🔐 安全

• 你的 API 密钥绝不会嵌入此包中。 它会在调用时从 OPENAI_API_KEY 读取。

• 除单次图像生成请求外，不会记录或传输任何内容。

• .env 和 out/ 目录默认被 git 忽略。

📝 注意与说明

• 每次请求通常需要约 10–60 秒，具体取决于端点和质量档位。

• 本项目与 OpenAI 无关；它是一个独立的 MCP 封装。

• gpt-image-2 默认以 base64 返回图像，此工具会将其解码并写入本地磁盘。同时也会处理 url 回退。

📄 许可证

MIT © Garfield-Wuu.

⭐ 支持

如果这个项目帮你免于在坑里折腾，欢迎点个 Star。也欢迎提交 Issue 和 PR。

🌐 Other languages / 其他语言

• 中文版 README (README.zh-CN.md) — 简体中文