Skip to main content
Glama
GPT Image 2 Polza MCP Server

GPT Image 2 Polza MCP Server

GPT Image 2 Polza MCP Server

mcp-name: io.github.ivanantigravity-lgtm/gpt-image-2-polza-mcp-server

MCP-сервер для генерации и редактирования изображений моделью GPT Image 2 через API-провайдера Polza.

  • Провайдер: Polza

  • Model ID: openai/gpt-5.4-image-2

  • Model tier: gpt-image-2

  • Поддержка генерации, редактирования и референсных изображений

  • Сохранение полноразмерных файлов на диск

  • Возврат превью и структурированных метаданных через MCP

Для работы нужен только POLZA_AI_API_KEY. Отдельный ключ OpenAI не требуется.

Инструменты MCP

  • generate_image — создаёт или редактирует изображения с помощью GPT Image 2.

  • fetch_generation — получает результат уже запущенной генерации по gen_... ID.

  • upload_file — загружает референс в Polza Storage.

  • show_output_stats — показывает статистику локальной папки с результатами.

  • maintenance — обслуживает локальный кэш и базу метаданных.

Related MCP server: openai-imagegen-mcp

Требования

  • Python 3.11+

  • uv

  • Аккаунт Polza и POLZA_AI_API_KEY

  • Любой MCP-клиент: Claude Code, Claude Desktop, Cursor, VS Code или другой

Быстрая установка

Клонируйте репозиторий:

git clone https://github.com/ivanantigravity-lgtm/gpt-image-2-polza-mcp.git
cd gpt-image-2-polza-mcp
uv sync

Создайте .mcp.json:

{
  "mcpServers": {
    "gpt-image-2-polza": {
      "command": "uv",
      "args": [
        "run",
        "gpt-image-2-polza-mcp-server"
      ],
      "cwd": "/absolute/path/to/gpt-image-2-polza-mcp",
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key",
        "POLZA_BASE_URL": "https://polza.ai/api",
        "IMAGE_OUTPUT_DIR": "/absolute/path/to/gpt-image-2-output"
      }
    }
  }
}

Перезапустите MCP-клиент после добавления конфигурации.

Использование

Обычная генерация:

Создай рекламный кадр флакона духов на чёрном камне,
кинематографический свет, формат 16:9, разрешение 4K.
Используй gpt-image-2.

Основные параметры generate_image:

Параметр

Описание

prompt

Текстовое описание изображения или инструкция по редактированию

mode

generate, edit или автоматическое определение

model_tier

gpt-image-2; используется по умолчанию

resolution

1k, 2k, 4k или high

aspect_ratio

Например, 1:1, 16:9, 9:16, 4:5

input_image_path_1

Путь к основному референсу или редактируемому изображению

input_image_path_2

Второй референс

input_image_path_3

Третий референс

output_path

Конкретный файл или папка для результата

force_new_generation

Принудительно запустить новую генерацию вместо использования кэша

Восстановление после таймаута

Генерация может продолжаться на стороне Polza после таймаута MCP-клиента. Не запускайте тот же запрос повторно сразу: это может создать и оплатить ещё одну генерацию.

Получите gen_... ID в истории генераций Polza и вызовите:

fetch_generation(
  media_id="gen_2158267363095220225",
  output_path="/absolute/path/to/result.png"
)

Переменные окружения

Переменная

Обязательно

Описание

POLZA_AI_API_KEY

Да

API-ключ аккаунта Polza

POLZA_BASE_URL

Нет

Базовый URL API; по умолчанию https://polza.ai/api

IMAGE_OUTPUT_DIR

Нет

Папка результатов; по умолчанию ~/gpt-image-2-images

GPT_IMAGE_MODEL

Нет

Model tier; по умолчанию gpt-image-2

POLZA_POLL_INTERVAL_SECONDS

Нет

Интервал проверки статуса генерации

POLZA_POLL_TIMEOUT_SECONDS

Нет

Максимальное время ожидания результата

POLZA_EXTERNAL_USER_ID

Нет

Внешний ID пользователя для Polza

RETURN_FULL_IMAGE

Нет

Возвращать полное изображение вместо превью

Локальный запуск

cp .env.example .env
uv sync
uv run gpt-image-2-polza-mcp-server

Минимальный .env:

POLZA_AI_API_KEY=your-polza-api-key
POLZA_BASE_URL=https://polza.ai/api
GPT_IMAGE_MODEL=gpt-image-2
IMAGE_OUTPUT_DIR=/absolute/path/to/gpt-image-2-output

API Polza

Сервер использует:

  • POST /v1/media — запуск генерации

  • GET /v1/media/{id} — получение статуса и результата

  • POST /v1/storage/upload — загрузка референсов

  • GET /v1/storage/files/{id} — метаданные файла

  • DELETE /v1/storage/files/{id} — удаление файла

Лицензия

MIT. См. LICENSE.

Available Tools

5 tools
fetch_generationFetch a Polza media generation by idD
Read-only

Inputs: media_id (required), wait, output_path.

generate_imageGenerate or edit images (Multi-Model: Flash & Pro)A
Read-only

Generate new images or edit existing images using natural language instructions.

Supports multiple input modes:

  1. Pure generation: Just provide a prompt to create new images

  2. Multi-image conditioning: Provide up to 3 input images using input_image_path_1/2/3 parameters

  3. File ID editing: Edit previously uploaded images using Files API ID

  4. File path editing: Edit local images by providing single input image path

Automatically detects mode based on parameters or can be explicitly controlled. Input images are read from the local filesystem to avoid massive token usage. Returns both MCP image content blocks and structured JSON with metadata.

Inputs: prompt (required), n, mode, file_id, +13 more.

maintenanceMaintenance and cleanup operationsB
Read-only

Perform maintenance operations following workflows.md patterns.

Available operations:

  • cleanup_expired: Remove expired Files API entries from database

  • cleanup_local: Clean old local files based on age/LRU

  • check_quota: Check Files API storage usage vs. ~20GB budget

  • database_hygiene: Clean up database inconsistencies

  • full_cleanup: Run all cleanup operations in sequence

Inputs: operation (required), dry_run, keep_count, max_age_hours.

show_output_statsShow output directory statsA
Read-only

Show statistics about the output directory and recently generated images.

Inputs: no named parameters.

upload_fileUpload file to Polza Storage APIA

Upload a local file through the Polza Storage API and return its URI & metadata. Useful when the image is larger than 20MB or reused across prompts.

Inputs: path (required), display_name.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 5 tools

    Disambiguation4/5

    generate_image, upload_file, show_output_stats, and maintenance each have clear and separate purposes. fetch_generation is the only ambiguous tool because it lacks a description and may be confused with retrieval or generation workflows.

    Naming Consistency4/5

    Four tools follow a verb_noun pattern (generate_image, upload_file, show_output_stats, fetch_generation), but maintenance is a bare noun instead of something like perform_maintenance. The pattern is still readable and mostly predictable.

    Tool Count5/5

    Five tools is well-scoped for an image generation server: one core generation tool, upload support, stats, fetch, and maintenance. Each tool covers a distinct functional area without redundancy.

    Completeness4/5

    The set covers the primary generation/editing, upload, retrieval, stats, and cleanup workflows. Minor gaps include no explicit per-file delete/list operations and fetch_generation's undocumented behavior, but agents can generally work around them via maintenance and cleanup.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers