imaginate-mcp

MCP-сервер, который создаёт и редактирует изображения с помощью OpenAI GPT Image и Google Gemini (Nano) (Nano Banana). Он работает через stdio, сохраняет каждое изображаение на диске и возвращает путь к файлу, чтобы ваш ассистент мог продолжить работу с резолютатом.

Что вы получите

Шесть инструментов, розспелённых по провайдерам:

Только те инструменты регистрируются, каким соответствуют настроеные keyчи. Если задать только OPENAI_API_KEY, ваш ассист увидит три "рументы, и ни one из них не сделать ошибку из-за отсутстствующего ключа Google. Это и был о главный причинno, by которой инструменты разедёнyt по провайдером, а не сдела ней как one струмент с аргументом provider.

Related MCP server: MCP OpenAI Image Generation Server

Требования

• Node.js 20 или новее

• API-ключ OpenAI, Gemin key or bothAPI both

Модели GPT Image требуют верификации orgанизации в OpenAI. Пока вы не прошли её, OpenAI откlonяt запрос, and server сообщит вам об этом.

Подключение

Запустите опубликованный пакт с npx. Можно not клonировать..

npx -y @pinkpixel/imaginate-mcp

Добавьте сервер в конфигурацyou. For Claude Desktop, отредактируйте claude_desktop_config.json. For Claude Code, use .mcp.json in a project or user's settings.

{
  "mcpServers": {
    "imaginate": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/imaginate-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "...",
        "IMAGINATE_OUTPUT_DIR": "~/Pictures/imaginate"
      }
    }
  }
}

После изменения конфигурации перзапустите клиент. If you have not yet появились image-инструменты, вызовите imaginate_setup_help. This инструмент есть только then, когda no provider is found, and he lists them in variables that you need to set.

Запуск из исходников

Клонируйте and соберите, if you want to work with server locally.

git clone https://github.com/pinkpixel-dev/imaginate-mcp.git
cd imaginate-mcp
npm install
npm run build
node dist/index.js

To подкл. MCP-клиент к этаму сборку, use "command": "node" and in args assign the absolute path to dist/index.js.

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

Все переменные считываются once at startup, so if you change some, restart the client.

Любой вызов can overridden output directory with output_dir, and file name via filename.

As working the files

Изображения попадают в выходной каталог. The server never overwrites anything. cat.png that already exists — becomes cat-1.png, then cat-2.png.

Имена по умолчанию look lie openin: tha is prefixed. Thas prefix, slug вашего запроса, and time stamp. If you want something specific, pass filename.

Sources for edit must be local files. Pass absolute paths. The tools are not downloads, so if the file is online, download it first. It only read and never changes.

Use

Server connected — basically you talk like ordinary to the assistant. A couple of things useful.

Choose provider

Both providers are good — in different.

Gemini is stronger on text inside images, world knowledge, and infographic work. It can rely on live Google Search results. It also returns an interaction ID — you can improve the picture without uploading again.

GPT Image is well meets detailed layout instructions and gives good control over size, quality, background. Need transparent background? Use it, but then you need gpt-image-1.5 or an older model, because gpt-image-2 removed it.

Iteration in Gemini image

Each turn result includes an interaction ID. Pass it forward as previous_interaction_id in next gemini_edit_image and not upload image again:

1. gemini_generate_image with a prompt. Return with the result includes ID.

2. gemini_edit_image with previous_interaction_id and the prompt «make it horizontal».

This is a cheap alternative to re-upload and more stable image between rounds.

Edit and composition

Both *_edit_image can handle several tasks through same interface. Pass one image path to edit it; pass several to assemble the new scene.

For mask inpainting the provides differ. OpenAI expects a real mask PNG with alpha channel, sent as mask. Gemini does it semantically: simply say «change only the sky and leave everything else» and skip the mask file.

Reference limit: 14 for Lite, 10 for Nano Banana 2, and 6 for Pro. In doubt, call gemini_list_image_models.

Development

npm run build      # compile to dist/
npm run watch      # compile on change
npm run typecheck  # types only, no output
npm test           # compile tests and run them

Tests use a built-in Node runner. They cover naming and saving, Gemini response parse, and error matching. No API call, so they run without keys.

The layout:

src/
  index.ts               entry point, conditional tool registration
  config.ts              environment parsing
  lib/                   file handling, errors, result formatting, model catalog
  providers/openai/      OpenAI client wrapper and tool definitions
  providers/google/      Gemini client wrapper and tool definitions
tests/

Ограничения

• Исходные images должны быть локальными — nothing on URL.

• Streaming output не реализована. A call is returned, when done.

• Gemini not reliable fulfilling amount, so button set one image per request. OpenAI the tools have n and it works.

• OpenAI может использовать до fifteen minutes per complicated request. That's API difference, server not guilty.

• Every image from Gemini contains invisible SynthID.

• Model IDs and prices move fast both. List tools show what version knows; actual access may differ.

Лицензия

Apache 2.0. Смо. LICENSE.

Made with 💖 — Pink Pixel.