gemini-webapi-mcp

Возможности

• Генерация изображений по текстовому описанию (Nano Banana 2 с поддержкой пропорций)

• 2x разрешение — автоматически скачивает upscaled-версию (2048x2048 → 2816x1536 и выше)

• Редактирование изображений — отправьте картинку + промпт и получите изменённую версию

• Анализ файлов — видео, изображения, PDF, документы

• Текстовый чат с Gemini (Flash, Pro, Flash-Thinking)

• Авто-удаление вотермарки — sparkle-метка Gemini убирается встроенным детерминированным Reverse Alpha Blending (без внешних бинарников, ML-моделей и скачиваний)

• Авто-аутентификация через cookies из Chrome

Related MCP server: NanoBanana MCP

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

1. Войдите в Gemini

Откройте Chrome, перейдите на gemini.google.com и войдите в свой Google-аккаунт.

2. Установите MCP-сервер

Из GitHub (без клонирования):

uv run --with "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git" gemini-webapi-mcp

Локальная установка:

git clone https://github.com/AndyShaman/gemini-webapi-mcp.git
cd gemini-webapi-mcp
uv sync
uv run gemini-webapi-mcp

3. Добавьте MCP-конфиг

claude mcp add-json gemini '{"command":"uv","args":["run","--with","gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git","gemini-webapi-mcp"]}'

Или добавьте вручную в .mcp.json в корне проекта:

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--with", "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git", "gemini-webapi-mcp"]
    }
  }
}

Добавьте в конфиг Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--with", "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git", "gemini-webapi-mcp"]
    }
  }
}

Используйте стандартный MCP stdio-конфиг:

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--with", "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git", "gemini-webapi-mcp"]
    }
  }
}

Путь к файлу конфига зависит от вашего MCP-клиента.

"args": ["--directory", "/path/to/gemini-webapi-mcp", "run", "gemini-webapi-mcp"]

4. Установите скилл для Claude Code (опционально)

Папка skill/ содержит скилл для Claude Code — подсказки по промптингу, документацию по тулам и гайд по генерации изображений. Скилл автоматически активируется при работе с Gemini.

cp -r skill ~/.claude/skills/gemini-mcp

5. Проверьте

Запустите сервер вручную — если инициализация прошла без ошибок, всё работает:

uv run --with "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git" gemini-webapi-mcp

После этого откройте Claude Code или Claude Desktop и попробуйте: «Сгенерируй картинку кота в акварельном стиле через Gemini».

Аутентификация

Сервер автоматически читает cookies из Chrome через browser-cookie3.

Несколько Google-аккаунтов? Установите GEMINI_ACCOUNT_INDEX — номер аккаунта из Chrome (0 = первый, 1 = второй, ...). Посмотрите порядок: кликните на аватарку в gemini.google.com.

Если автоопределение cookies не работает, задайте их вручную:

1. Откройте Chrome DevTools на gemini.google.com → Application → Cookies

2. Скопируйте значения __Secure-1PSID и __Secure-1PSIDTS

3. Добавьте в MCP-конфиг:

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--with", "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git", "gemini-webapi-mcp"],
      "env": {
        "GEMINI_PSID": "your__Secure-1PSID_value",
        "GEMINI_PSIDTS": "your__Secure-1PSIDTS_value"
      }
    }
  }
}

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

Высокое разрешение (2x)

Сервер автоматически запрашивает у Google увеличенную версию сгенерированного изображения — тот же механизм, что использует кнопка "Download" в веб-интерфейсе Gemini. Google выполняет server-side upscale, и вы получаете изображение в 2x разрешении:

Если 2x-версия недоступна (таймаут, ошибка сети), сервер автоматически использует нативное разрешение.

Удаление вотермарки

Gemini добавляет sparkle-метку (четырёхконечную звёздочку) в правый нижний угол сгенерированных изображений. Сервер убирает её встроенным алгоритмом Reverse Alpha Blending — original = (watermarked − premult) / (1 − alpha) — без внешних бинарников, ML-моделей и скачиваний.

Позиция и прозрачность метки детерминированы — они зависят только от того, был ли в запросе загружен файл-исходник, поэтому метка снимается без всякой детекции:

Логотип всегда 48 px (×2 при 2x-upscale). Так как сервер сам знает тип запроса, метка снимается чисто на любом фоне, включая тёмный. Откалиброванные alpha-карты лежат в src/gemini_webapi_mcp/assets/. Чтобы временно отключить удаление, задайте GEMINI_WM_KEEP=1.

Инструменты

Модели

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

После настройки MCP-конфига Claude сам вызывает нужные инструменты. Просто попросите в чате:

Инструменты, которые Claude вызовет:

gemini_generate_image(prompt="кот в акварельном стиле")
gemini_generate_image(prompt="сделай кота серым", files=["/path/to/cat.png"])
gemini_generate_image(prompt="сделай фон темнее", conversation_id=["c_abc", "r_123", "rc_456"])
gemini_analyze_url(url="https://youtube.com/watch?v=...", prompt="О чём это видео?")
gemini_upload_file(file_path="/path/to/doc.pdf", prompt="Сделай краткое резюме")

Благодарности

Этот проект построен на основе библиотеки gemini-webapi от @HanaokaYuzu (форк @xob0t с поддержкой curl_cffi) — реверс-инжиниринговой асинхронной Python-обёртки для веб-приложения Google Gemini. Лицензия: AGPL-3.0.

Алгоритм удаления вотермарки (Reverse Alpha Blending) изначально вдохновлён проектами gwt-mini от @allenk (Allen Kuo, MIT License) и gemini-watermark-remover от @GargantuaX (MIT License). В текущей версии сервер использует собственную встроенную реализацию и откалиброванные alpha-карты — внешние бинарники не требуются.

Лицензия

AGPL-3.0 — свободно используйте, модифицируйте и распространяйте при условии сохранения открытости исходного кода.

@AndyShaman · gemini-webapi-mcp

Features

• Image generation from text descriptions (Nano Banana 2 with aspect ratio support)

• 2x resolution — automatically downloads upscaled version (2048x2048 → 2816x1536 and above)

• Image editing — send an image + prompt to get a modified version

• File analysis — video, images, PDF, documents

• Text chat with Gemini (Flash, Pro, Flash-Thinking)

• Auto watermark removal — Gemini's sparkle mark is stripped by a built-in deterministic Reverse Alpha Blending pass (no external binaries, ML models, or downloads)

• Auto-authentication via Chrome browser cookies

Quick Start

1. Log into Gemini

Open Chrome, go to gemini.google.com and sign in.

2. Install the MCP server

From GitHub (no clone needed):

uv run --with "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git" gemini-webapi-mcp

Local install:

git clone https://github.com/AndyShaman/gemini-webapi-mcp.git
cd gemini-webapi-mcp
uv sync
uv run gemini-webapi-mcp

3. Add MCP config

claude mcp add-json gemini '{"command":"uv","args":["run","--with","gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git","gemini-webapi-mcp"]}'

Or add manually to .mcp.json in your project root:

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--with", "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git", "gemini-webapi-mcp"]
    }
  }
}

Add to Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--with", "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git", "gemini-webapi-mcp"]
    }
  }
}

Use the standard MCP stdio config:

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--with", "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git", "gemini-webapi-mcp"]
    }
  }
}

Config file path depends on your MCP client.

"args": ["--directory", "/path/to/gemini-webapi-mcp", "run", "gemini-webapi-mcp"]

4. Install the skill for Claude Code (optional)

The skill/ folder contains a Claude Code skill — prompting tips, tool documentation and an image generation guide. The skill auto-activates when working with Gemini.

cp -r skill ~/.claude/skills/gemini-mcp

5. Verify

Run the server manually — if it initializes without errors, everything works:

uv run --with "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git" gemini-webapi-mcp

Then open Claude Code or Claude Desktop and try: "Generate a watercolor cat image with Gemini".

Authentication

The server reads cookies from Chrome automatically via browser-cookie3.

Multiple Google accounts? Set GEMINI_ACCOUNT_INDEX — the account number from Chrome (0 = first, 1 = second, ...). Check the order by clicking your avatar on gemini.google.com.

If cookie auto-detection fails, set them manually:

1. Open Chrome DevTools on gemini.google.com → Application → Cookies

2. Copy __Secure-1PSID and __Secure-1PSIDTS values

3. Add to your MCP config:

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--with", "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git", "gemini-webapi-mcp"],
      "env": {
        "GEMINI_PSID": "your__Secure-1PSID_value",
        "GEMINI_PSIDTS": "your__Secure-1PSIDTS_value"
      }
    }
  }
}

Environment Variables

High Resolution (2x)

The server automatically requests an upscaled version of each generated image — the same mechanism used by the "Download" button in Gemini's web interface. Google performs server-side upscaling, delivering images at 2x resolution:

If the 2x version is unavailable (timeout, network error), the server automatically falls back to native resolution.

Watermark Removal

Gemini adds a sparkle watermark (4-point star) to the bottom-right corner of generated images. The server removes it with a built-in Reverse Alpha Blending pass — original = (watermarked − premult) / (1 − alpha) — with no external binaries, ML models, or downloads.

The mark's position and opacity are deterministic — they depend only on whether a source file was uploaded in the request, so the mark is removed without any detection:

The logo is always 48 px (×2 when 2x-upscaled). Since the server knows the request type, the mark is removed cleanly on any background, including dark ones. Calibrated alpha maps live in src/gemini_webapi_mcp/assets/. Set GEMINI_WM_KEEP=1 to disable removal.

Tools

Models

Usage Examples

Once configured, Claude calls the right tools automatically. Just ask in chat:

Tools that Claude will call:

gemini_generate_image(prompt="a cat in watercolor style")
gemini_generate_image(prompt="make it gray", files=["/path/to/cat.png"])
gemini_generate_image(prompt="make the background darker", conversation_id=["c_abc", "r_123", "rc_456"])
gemini_analyze_url(url="https://youtube.com/watch?v=...", prompt="Summarize this video")
gemini_upload_file(file_path="/path/to/doc.pdf", prompt="Summarize key points")

Acknowledgements

This project is built on top of gemini-webapi by @HanaokaYuzu (fork by @xob0t with curl_cffi support) — a reverse-engineered async Python wrapper for the Google Gemini web app. Licensed under AGPL-3.0.

The watermark-removal algorithm (Reverse Alpha Blending) was originally inspired by gwt-mini by @allenk (Allen Kuo, MIT License) and gemini-watermark-remover by @GargantuaX (MIT License). The current version uses its own built-in implementation and calibrated alpha maps — no external binaries required.

License

AGPL-3.0 — free to use, modify, and distribute, provided the source code remains open.

@AndyShaman · gemini-webapi-mcp