gemini-webapi-mcp

MCP-сервер для Google Gemini — генерация и редактирование изображений, чат и анализ файлов через браузерные cookies.
Без API-ключей. Бесплатно.

Возможности

• Генерация изображений по текстовому описанию (Nano Banana 2 с поддержкой пропорций)
• 2x разрешение — автоматически скачивает upscaled-версию (2048x2048 → 2816x1536 и выше)
• Редактирование изображений — отправьте картинку + промпт и получите изменённую версию
• Анализ файлов — видео, изображения, PDF, документы
• Текстовый чат с Gemini (Flash, Pro, Flash-Thinking)
• Авто-удаление вотермарки — sparkle-метка Gemini убирается встроенным детерминированным Reverse Alpha Blending (без внешних бинарников, ML-моделей и скачиваний)
• Авто-аутентификация через 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
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"]}'

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

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

{
  "mcpServers": {
    "gemini": {
      "command": "uv",
      "args": ["run", "--with", "gemini-webapi-mcp @ git+https://github.com/AndyShaman/gemini-webapi-mcp.git", "gemini-webapi-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-вычитанием — original = (L − A·shape·255) / (1 − A·shape) — без внешних бинарников, ML-моделей и скачиваний.

Метка всегда стоит в одном из двух фиксированных угловых якорей — на отступе 96 px или 32 px от правого нижнего угла (абсолютные отступы, не зависят от разрешения; логотип 48 px, ×2 при 2x-upscale). Сервер не детектирует метку по порогу корреляции — это ненадёжно на ярком фоне, где слабая полупрозрачная звёздочка почти не контрастирует. Вместо этого он детерминированно обрабатывает оба якоря:

1. per-image прозрачность — сила метки оценивается из самого кадра (L = bg + A·shape·(255−bg), least-squares); на пустом якоре A ≈ 0, поэтому вычитание становится no-op;
2. reverse-alpha в позиции якоря;
3. self-check по |corr| — вычитание принимается, только если оно уменьшает корреляцию с формой звезды; иначе откатывается. Навредить пустому, текстурному или цветному-контентному якорю невозможно.

Подход не содержит ни одной захардкоженной «под разрешение» величины, поэтому работает на любом нативном разрешении и соотношении сторон — на светлом, тёмном и цветном фоне.

Единственный калиброванный инвариант — форма звезды в src/gemini_webapi_mcp/assets/wm_alpha_edit.npy. Чтобы временно отключить удаление (получить «сырой» водяной знак), задайте 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

gemini-webapi-mcp

MCP server for Google Gemini — image generation/editing, chat and file analysis via browser cookies.
No API keys. Free.

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"]}'

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

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

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

"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-blend — original = (L − A·shape·255) / (1 − A·shape) — with no external binaries, ML models, or downloads.

The mark is always stamped at one of two fixed corner anchors — 96 px or 32 px from the bottom-right (absolute offsets that don't depend on resolution; the logo is 48 px, ×2 when 2x-upscaled). The server does not detect the mark by a correlation threshold — that's unreliable on bright backgrounds, where a faint translucent star barely contrasts. Instead it deterministically processes both anchors:

1. per-image opacity — the mark's strength is fit from the frame itself (L = bg + A·shape·(255−bg), least-squares); on an empty anchor A ≈ 0, so the subtraction is a no-op;
2. reverse alpha-blend at the anchor;
3. |corr| self-check — a subtraction is accepted only if it reduces the correlation with the star shape; otherwise it is reverted. It can never damage an empty, textured, or coloured-content anchor.

The approach hard-codes no resolution-dependent values, so it works at any native resolution or aspect ratio — on light, dark, and coloured backgrounds alike.

The only calibrated invariant is the star shape in src/gemini_webapi_mcp/assets/wm_alpha_edit.npy. Set GEMINI_WM_KEEP=1 to disable removal (keep the raw watermark).

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