mcp-alphabanana

English | 日本語

mcp-alphabanana — это сервер протокола Model Context Protocol (MCP) для генерации изображений с помощью Google Gemini. Он создан для MCP-совместимых клиентов и агентских рабочих процессов, которым требуется быстрая генерация изображений, прозрачный вывод, использование референсных изображений и гибкие форматы доставки.

Ключевые слова: MCP-сервер, Model Context Protocol, Gemini AI, генерация изображений, FastMCP

Основные возможности:

• Сверхбыстрая генерация изображений Gemini в версиях Flash и Pro

• Вывод ресурсов в форматах PNG/WebP с прозрачностью для веб-разработки и игровых конвейеров

• Управление стилем с помощью нескольких локальных референсных изображений

• Гибкие варианты вывода: файл, base64 или комбинированный для агентских рабочих процессов

Быстрый старт

Запустите MCP-сервер с помощью npx:

npx -y @tasopen/mcp-alphabanana

Или добавьте его в свою конфигурацию MCP:

{
  "mcp": {
    "servers": {
      "alphabanana": {
        "command": "npx",
        "args": ["-y", "@tasopen/mcp-alphabanana"],
        "env": {
          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
        }
      }
    }
  }
}

Установите GEMINI_API_KEY перед запуском сервера.

Для Claude Desktop: Скачайте mcp-alphabanana-latest.mcpb, затем добавьте его как расширение в настройках Claude Desktop. Для Windows рекомендуется добавить расширение 'FileSystem' для более удобной работы с локальными файлами.

Реестр Claude

Метаданные реестра Claude / пакета MCPB определены в manifest.json и поставляются со статичным значком 512x512 по адресу images/mcp-alphabanana.png.

Собственные пакеты среды выполнения sharp объявлены как необязательные зависимости, чтобы установки .mcpb могли разрешать правильный предварительно скомпилированный бинарный файл на каждой поддерживаемой платформе без использования хуков postinstall.

• Стабильный URL MCPB: https://github.com/tasopen/mcp-alphabanana/releases/latest/download/mcp-alphabanana-latest.mcpb

• Шаблон версионного URL MCPB: https://github.com/tasopen/mcp-alphabanana/releases/download/vVERSION/mcp-alphabanana-VERSION.mcpb

• Поддержка: GitHub Issues

MCP-сервер

Этот репозиторий предоставляет MCP-сервер, который позволяет ИИ-агентам генерировать изображения с помощью Google Gemini.

Его можно использовать с MCP-совместимыми клиентами, такими как:

• Claude Desktop

• VS Code MCP

• Cursor

Создан с использованием FastMCP 3 для упрощения кодовой базы и гибких параметров вывода.

Бейдж Glama MCP Server:\

Доступные инструменты

generate_image

Генерирует изображения с помощью Google Gemini с поддержкой прозрачности, локальных референсных изображений, поиска (grounding) и метаданных рассуждений.

Для Claude Desktop предпочтительнее использовать outputType=file для изображений среднего или большого размера. Ответы base64 и combine потребляют контекст Claude и могут достичь лимита размера клиента. В Windows используйте расширение FileSystem, чтобы выбрать записываемый абсолютный путь outputPath и любые локальные пути referenceImages.

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

• prompt (строка): описание изображения для генерации

• model: Flash3.1, Flash2.5, Pro3, flash, pro

• outputWidth и outputHeight: требуемый итоговый размер изображения в пикселях в обычном режиме

• noresize + aspectRatio + output_resolution: возврат исходного размера Gemini без изменения размера

• output_resolution: 0.5K, 1K, 2K, 4K

• output_format: png, jpg, webp

• outputType: file, base64, combine

• outputPath: обязательно, если outputType равен file или combine

• transparent: включить постобработку прозрачности PNG/WebP

• referenceImages: необязательный массив локальных референсных изображений

• grounding_type и thinking_mode: расширенные элементы управления Gemini 3.1

Выбор модели

Параметры

Полный справочник параметров для инструмента generate_image.

Почему alphabanana?

• Без водяных знаков: Чистые изображения, созданные API.

• Поддержка Thinking/Grounding: Более точное следование промпту и точность, подкрепленная поиском.

• Готовность к продакшену: Поддержка прозрачного WebP и точных соотношений сторон для веб-ресурсов и игровых ассетов.

Функции

• Сверхбыстрая генерация изображений (Gemini 3.1 Flash, 0.5K/1K/2K/4K)

• Расширенное рассуждение по нескольким изображениям (до 14 референсных изображений)

• Поддержка Thinking/Grounding (только Flash3.1)

• Вывод прозрачных PNG/WebP (постобработка цветового ключа, удаление ореолов)

• Несколько форматов вывода: файл, base64 или оба

• Гибкие режимы изменения размера: обрезка, растяжение, letterbox, contain

• Несколько уровней моделей: Flash3.1, Flash2.5, Pro3, устаревшие псевдонимы

Примеры вывода

Эти примеры вывода были сгенерированы с помощью mcp-alphabanana и сохранены в images/examples.

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

Настройте GEMINI_API_KEY в вашей конфигурации MCP (например, mcp.json).

Примеры:

• Ссылка на переменную окружения ОС из mcp.json:

{
  "env": {
    "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
  }
}

• Указание ключа напрямую в mcp.json:

{
  "env": {
    "GEMINI_API_KEY": "your_api_key_here"
  }
}

Интеграция с VS Code

Добавьте в настройки VS Code (.vscode/settings.json или настройки пользователя), настроив env сервера в mcp.json или через настройки VS Code MCP.

{
  "mcp": {
    "servers": {
      "mcp-alphabanana": {
        "command": "npx",
        "args": ["-y", "@tasopen/mcp-alphabanana"],
        "env": {
          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
        }
      }
    }
  }
}

Необязательно: Установите пользовательскую резервную директорию для сбоев записи, добавив MCP_FALLBACK_OUTPUT в объект env.

Примеры использования

Базовая генерация

{
  "prompt": "A pixel art treasure chest, golden trim, wooden texture",
  "model": "Flash3.1",
  "outputFileName": "chest",
  "outputType": "base64",
  "outputWidth": 64,
  "outputHeight": 64,
  "transparent": true
}

Исходный размер без изменения размера

{
  "prompt": "A clean app icon with a banana mascot, flat graphic design",
  "model": "Flash3.1",
  "outputFileName": "banana-icon-native",
  "outputType": "base64",
  "noresize": true,
  "aspectRatio": "1:1",
  "output_resolution": "0.5K",
  "output_format": "png"
}

Этот режим возвращает исходный размер в пикселях Gemini для запрошенного соотношения и разрешения. Например, 1:1 + 0.5K возвращает 512x512 без прохода изменения размера.

Расширенный (вертикальный постер и мышление)

{
  "prompt": "A vertical, photorealistic travel poster advertising Magical Wings Day Tours. A joyful young couple flies high above a breathtaking European countryside at golden hour, holding hands as they soar through a partly cloudy sky. Below them are vineyards, villages, forests, a winding river, and a hilltop medieval castle. The poster uses large, elegant typography with the headline FLY THE COUNTRYSIDE at the top and Magical Wings Day Tours branding near the bottom.",
  "model": "Flash3.1",
  "output_resolution": "1K",
  "outputFileName": "photoreal-travel-poster",
  "outputType": "file",
  "outputPath": "/path/to/output",
  "outputWidth": 848,
  "outputHeight": 1264,
  "output_format": "jpg",
  "thinking_mode": "high",
  "include_metadata": true
}

Пример Grounding (с поиском)

{
  "prompt": "A modern travel poster featuring today's weather and skyline highlights in Kuala Lumpur",
  "model": "Flash3.1",
  "outputFileName": "kl_travel_poster",
  "outputType": "base64",
  "outputWidth": 1024,
  "outputHeight": 1024,
  "grounding_type": "text",
  "thinking_mode": "high",
  "include_metadata": true,
  "include_thoughts": true
}

Этот пример включает поиск в Google и возвращает метаданные поиска и рассуждений в формате JSON.

С референсными изображениями

{
  "prompt": "Use the reference image to create a game screen showing an opened treasure chest filled with coins and treasure, 8-bit dungeon crawler style, after-battle reward scene, dungeon corridor background, four-party status UI at the bottom",
  "model": "Flash3.1",
  "output_resolution": "0.5K",
  "outputFileName": "reference-image-dungeon-loot",
  "outputType": "file",
  "outputPath": "/path/to/output",
  "outputWidth": 600,
  "outputHeight": 448,
  "output_format": "webp",
  "transparent": false,
  "referenceImages": [
    {
      "description": "Treasure chest style reference",
      "filePath": "/path/to/references/pixel-art-treasure-chest.png"
    }
  ]
}

Прозрачность и форматы вывода

• PNG: Полная альфа, цветовой ключ + удаление ореолов

• WebP: Полная альфа, лучшее сжатие (Flash3.1+)

• JPEG: Без прозрачности (заменяется сплошным фоном)

Разработка

# Development mode with MCP CLI
npm run dev

# MCP Inspector (Web UI)
npm run inspect

# Build for production
npm run build

Лицензия

MIT