gemini-webapi-mcp

Возможности

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

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

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

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

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

• Авто-удаление вотермарки — sparkle-метка Gemini убирается через gwt-mini от @allenk (поддержка профилей Gemini 3.5 и legacy, macOS / Windows / Linux)

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

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

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
python scripts/install_gwt.py   # опционально: удаление вотермарки (см. ниже)
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-метку (четырёхконечную звёздочку) в правый нижний угол сгенерированных изображений. Сервер вызывает CLI-утилиту gwt-mini от @allenk — она реализует Reverse Alpha Blending с поддержкой профилей Gemini 3.5 и legacy и работает в офлайне, без ML-моделей.

Установка одной командой из корня клонированного репозитория (macOS, Linux, Windows):

python scripts/install_gwt.py

Скрипт скачивает бинарник gwt-mini из релизов allenk/GeminiWatermarkTool, проверяет SHA-256 и кладёт в tools/gwt/. Бинарник не коммитится в репозиторий. Без него сервер продолжает работать — просто оставляет вотермарку на месте и пишет предупреждение в лог. Чтобы временно отключить удаление, задайте 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.

Удаление вотермарки выполняется бинарником gwt-mini от @allenk (Allen Kuo, MIT License) — он реализует алгоритм Reverse Alpha Blending и держит откалиброванные профили под текущий и legacy формат метки. Калибровочные alpha-карты для legacy-профиля изначально пришли из gemini-watermark-remover от @GargantuaX (MIT License). Бинарник скачивается локально скриптом scripts/install_gwt.py и не входит в этот репозиторий.

Лицензия

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 via gwt-mini by @allenk (Gemini 3.5 + legacy profiles, macOS / Windows / Linux)

• 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
python scripts/install_gwt.py   # optional: watermark removal (see below)
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 shells out to gwt-mini by @allenk — it implements Reverse Alpha Blending with calibrated profiles for both current Gemini 3.5 and the legacy mark, runs offline, no ML models.

Install with one command from a cloned checkout (macOS, Linux, Windows):

python scripts/install_gwt.py

The script downloads the gwt-mini binary from allenk/GeminiWatermarkTool releases, verifies the SHA-256, and places it under tools/gwt/. The binary is not committed. Without it the server keeps working — it just leaves the watermark in place and logs a warning. Set GEMINI_WM_KEEP=1 to disable removal even when the binary is installed.

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.

Watermark removal is performed by the gwt-mini binary by @allenk (Allen Kuo, MIT License) — it implements Reverse Alpha Blending and ships calibrated profiles for both the current and legacy Gemini sparkle. Legacy-profile alpha maps originally came from gemini-watermark-remover by @GargantuaX (MIT License). The binary is fetched locally by scripts/install_gwt.py and is not redistributed with this repository.

License

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

@AndyShaman · gemini-webapi-mcp