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 не нужна — достаточно любого API-ключа, поддерживающего gpt-image-2.

Рабочий процесс:

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 → stdio MCP-сервер с инструментами generate_image / list_images

  • gpt-image-mcp "a cat in a spacesuit" → однократная генерация через CLI

• Любой OpenAI-совместимый бэкенд. Указывайте OPENAI_BASE_URL куда угодно (реселлеры, прокси, самостоятельные шлюзы).

• Уровни качества соответствуют собственному параметру gpt-image-2: low / medium / high. Никаких лишних моделей и неожиданных затрат.

• Ключи никогда не попадают в код. Всё управляется через переменные окружения — секреты не попадают в ваш репозиторий.

• Асинхронно-безопасно. Изображения потоково сохраняются на диск как локальные PNG, декодированные из base64; API никогда не пишет на ваш диск.

🧰 Требования

• Python 3.10+

• Ключ OpenAI API или OpenAI-совместимая конечная точка (реселлер / шлюз / самостоятельный хостинг), предоставляющая gpt-image-2 (или совместимую модель, задаваемую через GPT_IMAGE_MODEL).

• Python, устанавливаемый через pip или uv.

📦 Установка

Из 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

«Сгенерируй ландшафтный hero-снимок 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 CLI позволяет интерактивно выбрать размер/качество, когда доступен TTY.

🖼️ Параметры

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.

⭐ Поддержка

Если это избавило вас от долгих поисков, звёздочка будет приятна. Приветствуются issues и PR.

🌐 Другие языки / 其他语言

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