Gemini Image MCP

Сервер MCP для генерации и редактирования изображений с помощью моделей Gemini от Google (Nano Banana, Nano Banana 2, Nano Banana Pro). Он предоставляет один инструмент — generate_image, который AI-инструменты, такие как Claude, Codex и Cline, могут вызывать, используя ваш собственный API-ключ.

Что он делает

• generate_image обрабатывает текст-в-изображение, а также редактирование и композицию, когда вы передаёте ему эталонные изображения (локальные пути к файлам или base64).

• Каждый параметр генерации доступен при каждом вызове: temperature (1), topP (0,95), topK, maxOutputTokens (65536 для flash/lite, 32768 для pro), seed, stopSequences, presencePenalty, frequencyPenalty, systemInstruction, thinkingLevel (minimal/high), thinkingBudget, enableGoogleSearch (по умолчанию true), imageSize (512/1K/2K/4K), aspectRatio ("auto" по умолчанию + стандартные соотношения), personGeneration.

• Поставляется с блоком instructions и описаниями каждого параметра, поэтому MCP-клиенты разбираются, как использовать инструмент, без дополнительных подсказок.

• Сохраняет изображения на диск и возвращает пути к файлам. В ответе нет base64, поэтому изображение 4K не съест контекстное окно клиента.

• Ошибки возвращаются с подсказками (неверный ключ, превышение лимита, блокировка безопасности, неизвестная модель), а не в виде сырого дампа API.

• Транспорт stdio — стандартная настройка для локальных MCP-серверов.

Требования

• Bun 1.0+

• API-ключ Gemini с https://aistudio.google.com/apikey

Установка

bun install

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

Три переменные окружения, обычно задаваемые в конфиге MCP-клиента:

Модели, которые можно выбрать:

Модели также можно указывать с префиксом models/ (например, models/gemini-3.1-flash-image).

Настройка клиента

Claude Desktop

Добавьте это в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Cline (VS Code)

cline_mcp_settings.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.gemini-image]
command = "bun"
args = ["run", "/absolute/path/to/gemini-image-mcp/index.ts"]
env = { GEMINI_API_KEY = "YOUR_KEY_HERE" }

Из npm (bunx/npx)

После публикации пакета укажите клиенту bunx вместо этого:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bunx",
      "args": ["gemini-image-mcp"],
      "env": { "GEMINI_API_KEY": "YOUR_KEY_HERE" }
    }
  }
}

Параметры generate_image

Обязателен только prompt. Всё остальное по умолчанию принимает разумные значения для генерации изображений.

Инструмент возвращает текстовую сводку с путём(ями) к сохранённому файлу, моделью, фактической конфигурацией и использованием токенов. Он никогда не возвращает данные изображения в строке; откройте файл, чтобы увидеть результат.

Что можно попросить у вашего AI

• "Сгенерируй изображение 16:9 для героя — дождливая улица Токио ночью, кинематографическое неоновое освещение."

• "Отредактируй /tmp/product.png: помести его на мраморный стол с мягким утренним светом" (это использует referenceImages).

• "Сгенерируй плакат 4K с точным заголовком 'LAUNCH DAY', используя gemini-3-pro-image."

Разработка

bun test              # unit tests (config, schema, request/response parsing)
bun run typecheck     # tsc --noEmit
bun run inspector     # interactive MCP inspector (needs GEMINI_API_KEY)
bun run start         # run the server on stdio

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

• "Отсутствует API-ключ Gemini": поместите GEMINI_API_KEY в блок env конфигурации MCP клиента. Установка в оболочке недостаточна для GUI-приложений, таких как Claude Desktop, поскольку они не читают среду оболочки.

• Блокировки безопасности: переформулируйте запрос (prompt). Если на изображении люди, проверьте personGeneration.

• 429 / превышение квоты: подождите и повторите попытку или используйте gemini-3.1-flash-image, у которой выше квота.

• Логи: сервер записывает логи только в stderr. stdout передаёт протокол MCP, поэтому не добавляйте console.log нигде.

Автор

Thomi Jasir dev@venobi.com

Лицензия

MIT