gemini-image-mcp-http

Удалённый MCP-сервер (Streamable HTTP): генерация и редактирование изображений через Google Gemini 3.1 Flash Image («Nano Banana 2»), который можно подключить к Claude.ai в браузере (а также Claude Desktop/Cowork/мобильным приложениям) как Custom Connector.

Проверено локально: сервер поднимается, отвечает на MCP initialize/tools/list/tools/call, неверный секрет в URL получает 404. Единственное, что нельзя было протестировать здесь — сам вызов Gemini API (в песочнице нет доступа к generativelanguage.googleapis.com), но запрос к нему формируется по официальной REST-схеме Gemini.

Как это устроено

• Один HTTP-эндпоинт: POST/GET /mcp/<MCP_SHARED_SECRET>
• <MCP_SHARED_SECRET> — длинная случайная строка, которую вы сами зададите. Она одновременно служит и частью URL, и защитой: без неё запрос получает 404. Никому не показывайте итоговый URL целиком.
• Внутри — два инструмента: generate_image и edit_image, оба обращаются к Gemini REST API вашим ключом (ключ хранится только на сервере, Claude его не видит).
• Изображение возвращается сразу в чат (как картинка), без сохранения на диск — на большинстве хостингов файловая система эфемерна, так что это осознанный выбор.

⚠️ Про ключ, который вы уже присылали в чат: это больше похоже не на обычный Gemini API-ключ (те выглядят как AIzaSy...), а на другой тип токена Google. Перед деплоем зайдите на https://aistudio.google.com/apikey, создайте (или перевыпустите) именно API-ключ и используйте его — не токен из чата.

---

Шаг 1. Сгенерируйте секрет

openssl rand -hex 24

Сохраните результат — это будет и MCP_SHARED_SECRET, и часть URL коннектора.

Шаг 2. Задеплойте сервер

Ниже — вариант через Render.com (проще всего для одного файла, есть бесплатный план). Подойдут и Railway/Fly.io/любой VPS — везде логика одна: Node 18+, переменные окружения, публичный HTTPS-домен. В архиве есть Dockerfile, так что подойдёт и любой Docker-хостинг.

Render.com (без своего сервера)

1. Зайдите на https://render.com → New → Web Service.
2. Вариант «Deploy an existing image / upload code» — загрузите содержимое этой папки в свой GitHub-репозиторий (пустой репозиторий, залить файлы можно и через веб-интерфейс GitHub) и подключите его к Render.
3. Runtime: Node. Build command: npm install. Start command: npm start.
4. В разделе Environment добавьте:
   • GEMINI_API_KEY = ваш настоящий ключ из AI Studio
   • MCP_SHARED_SECRET = строка из шага 1
   • (необязательно) GEMINI_IMAGE_MODEL = gemini-3.1-flash-image
5. Deploy. После сборки Render даст домен вида https://ваш-сервис.onrender.com.

Через Docker (Fly.io / Railway / свой VPS)

docker build -t gemini-image-mcp-http .
docker run -p 3000:3000 \
  -e GEMINI_API_KEY=ваш-ключ \
  -e MCP_SHARED_SECRET=строка-из-шага-1 \
  gemini-image-mcp-http

Дальше — по инструкции конкретного хостинга, как опубликовать контейнер на HTTPS-домене (на Fly.io — fly launch + fly deploy, на Railway — просто подключить репозиторий).

Шаг 3. Проверьте, что сервер отвечает

curl https://ваш-домен/           # health-check, должен вернуть "OK"

Шаг 4. Добавьте коннектор в Claude.ai

1. В Claude.ai: Settings → Connectors (или «Настроить» → «Коннекторы»).
2. Нажмите «+» → Add custom connector.
3. В поле URL укажите:

   https://ваш-домен/mcp/MCP_SHARED_SECRET_СЮДА
   

   (полный секретный URL, без пробелов)
4. Advanced settings можно оставить пустыми — авторизация уже встроена в сам URL.
5. Нажмите «Add», затем включите коннектор для нужного чата через «+» → Connectors.

Готово — в чате можно будет попросить: «сгенерируй через Gemini картинку рыжего кота на подоконнике» или «отредактируй это изображение: сделай фон синим».

---

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

Переменная	Обязательна	По умолчанию	Описание
GEMINI_API_KEY	да	—	Ключ Gemini API из Google AI Studio
MCP_SHARED_SECRET	да	—	Секрет в URL, защищающий эндпоинт от чужих
GEMINI_IMAGE_MODEL	нет	gemini-3.1-flash-image	Имя модели
PORT	нет	3000	Обычно задаётся хостингом автоматически
S3_ENDPOINT	нет	—	Эндпоинт S3-совместимого хранилища (см. ниже)
S3_BUCKET	нет	—	Имя бакета
S3_ACCESS_KEY_ID	нет	—	Access key
S3_SECRET_ACCESS_KEY	нет	—	Secret key
S3_REGION	нет	auto	Регион (для R2 оставить auto)
S3_PUBLIC_URL	нет	собирается из endpoint+bucket	Публичный базовый URL для отдачи файлов
S3_FORCE_PATH_STYLE	нет	true	Path-style URL (нужно для R2/MinIO)
PUBLIC_BASE_URL	нет	определяется автоматически	Базовый URL сервиса — для ссылок локального фолбэка

Постоянное хранение изображений (важно!)

Каждый вызов generate_image/edit_image всегда сохраняет файл целиком, независимо от его веса и разрешения, и возвращает в ответе текстовую ссылку Image URL: .... Инлайн-превью в самом чате при этом появляется только если файл укладывается в безопасный лимит показа (~900 КБ) — но ссылка работает всегда, для файлов любого размера.

Есть два режима:

1. Без настройки (по умолчанию). Файлы хранятся в памяти самого сервиса и отдаются по адресу /images/<id>.<ext>. Просто и без доп. шагов, но:

   • ссылки живут максимум 6 часов;
   • на бесплатном тарифе Render контейнер засыпает при простое и теряет память при перезапуске — старые ссылки после этого перестают открываться.

2. С постоянным хранилищем (рекомендуется) — Cloudflare R2.

   1. Зайдите в Cloudflare Dashboard → R2 → Create bucket. Название, например gemini-images.
   2. В настройках бакета включите публичный доступ (Public Access → Allow Access), скопируйте выданный публичный URL (https://pub-xxxxxxxx.r2.dev) — это и есть S3_PUBLIC_URL.
   3. R2 → Manage API Tokens → Create API Token → права Object Read & Write на этот бакет. Скопируйте Access Key ID, Secret Access Key и Account ID.
   4. В переменных окружения хостинга (Render → ваш сервис → Environment) добавьте:

      S3_ENDPOINT=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
      S3_BUCKET=gemini-images
      S3_ACCESS_KEY_ID=<access key>
      S3_SECRET_ACCESS_KEY=<secret key>
      S3_PUBLIC_URL=https://pub-xxxxxxxx.r2.dev
      

   5. Redeploy. В логах при старте должно появиться: Постоянное хранилище: S3-совместимое (https://<ACCOUNT_ID>.r2.cloudflarestorage.com).
   6. Готово — теперь ссылки на изображения не пропадают ни при засыпании сервиса, ни при редеплое, и работают для файлов любого веса и разрешения (1K/2K/4K).

   Вместо R2 подойдёт любое S3-совместимое хранилище (AWS S3, Backblaze B2, MinIO) — просто укажите соответствующие S3_ENDPOINT/регион.

Безопасность и стоимость

• Секрет в URL — единственная защита. Держите ссылку приватной, не публикуйте её, не коммитьте в открытый репозиторий вместе со значением переменных окружения.
• Каждый вызов generate_image/edit_image тратит квоту/деньги вашего Gemini-ключа — теоретически любой, кто узнает секретный URL, сможет им пользоваться. Если нужна более серьёзная защита (OAuth, ротация секрета, лимиты запросов) — можно усилить отдельно, дайте знать.
• Хотите вообще не выставлять свой Gemini-ключ в интернет — тогда лучше вариант из первого архива (gemini-image-mcp.zip) под Claude Desktop: там сервер работает локально на вашей машине и никуда наружу не торчит.