image-generation-mcp

Попросите своего агента нарисовать картинку — и он получит путь к файлу, а не простыню base64. Сервер генерирует изобржение с помощью Gemini или OpenAI, записывает его на диск и возвращает только абсолютный путь. Ваше контекстное окно остаётся чистым, а файл тут же доступен агенту — открыть, переместить или передать другому инструменту.

Возможности

• Один инструмент, без лишних церемоний. generate_image(prompt, images, aspect_ratio) — вот и весь API.

• Пути, а не пеяды. Возвращает абсолютный путь к файлу, так что PNG на 1,5 МБ обходится вам в ~60 токенов вместо ~2 милллионов.

• Два провайдера с автовыбором. Укажите тот API-ключ, который у вас есть. Заданы оба? Решает IMAGE_PROVIDER.

• Изобржение-к-изобржению. Передайте до 4 референсных изобржений, чтобы перестилизовать, отредактировать или объединить их.

• Гибкие входные данные. Референс может быть локальным путём, URL вида http(s), URI вида data: или просто base64 — сервер сам разберётся.

• Оба транспорта. stdio для локальных клиентов, потоковый HTTP (с привязкой к localhost) — когда нужен порт.

• Честные ошибки. Никаких повторов, скрывающих неверный ключ, и никакого тихого переключения провайдера. Когда API отвечает 429, вы видите 429.

• Достаточно мал, чтобы прочитать. ~540 строк исходного кода, ни один файл не больше 100 строк, строгая типизация повсюду.

Related MCP server: VisionToolMCP

Предварительные требования

Примечание об оплате. Модели изображений не входят в бесплатный тариф ни у одного из провайдеров. Ключ Gemini без включённого биллинга возвращает 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/

Эта последняя команда — самый быстрый способ убедиться, что ключ работает по полному циклу: она печатает путь к только что созданному изображению.

Подключение к вашему агенту

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 mcp list, а удалите — 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"
      }
    }
  }
}

Задайте OUT_DIR явно для GUI-клиентов — они часто запускаются с рабочей директорией, которую вы не ожидали, и out/ оказался бы там.

Как HTTP-сервис

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

Сервер отдаёт endpoint потокового HTTP на http://127.0.0.1:8000/mcp. Он привязан только к loopback и не имеет аутентификации, поэтому перед публикацией поместите его за прокси.

Инструмент

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

Возвращает абсолютный путь к записанному файлу, например /path/to/out/20260827-172746-c9b3.png. Имена имеют формат YYYYmmdd-HHMMSS-xxxx, так что результаты сортируются по времени и никогда не конфликтуют.

О соотношениях сторон: Gemini поддерживает все десять. OpenAI принимает только три размера, поэтому соотношения сводятся к ближайшему из 1024x1024, 1536x1024 или 1024x1536 — запрос 16:9 там даст вам 3:2.

Конфигурация

Каждая настройка — это переменная окружения. Файл .env в рабочей директории (или в любом родительском каталоге) загружается как запасной вариант; настоящие переменные окружения всегда имеют приоритет.

Запустите сервер вообще без API-ключа — и первый же запрос завершится с громкой ошибкой, называющей переменные, которые сервер искал.

Как это работает

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 для изображений принимает только image/jpeg как явный MIME-тип, поэтому сервер не запрашивает его и называет файл по тому, что вернулось.

• 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 стоит две генерации, потому что создаёт собственное референсное изображение.

Логотип и скриншот тоже создаются генерацией — редактируйте скрипты, а не SVG:

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

Ограничение в 100 строк на файл — это осознанное проектное решение, а не случайность: благодаря ему каждый модуль можно просмотреть на одном экране. Лучше разбивать, чем растягивать.

Устранение неполадок

Лицензия

MIT © Ömer Faruk Can