gemini-webapi-mcp
This server lets AI assistants use Google Gemini (via browser cookies, no API key) for image generation/editing, file/URL analysis, and chat.
Generate images from text prompts (Nano Banana 2, aspect-ratio support)
Edit images by providing existing images + prompt
Refine images iteratively using conversation IDs from previous generations
Get 2x upscaled images automatically (fallback to native resolution)
Remove Gemini watermark automatically from generated images (disable with
GEMINI_WM_KEEP=1)Analyze files — upload images, PDFs, documents, or videos and ask questions
Analyze URLs — YouTube videos, webpages, articles
Chat with Gemini — single-turn or multi-turn sessions
Start multi-turn chat sessions to maintain conversation context
Reset/re-initialize the client on auth errors or to refresh cookies
Authenticate automatically via Chrome cookies, with manual cookie fallback (
GEMINI_PSID,GEMINI_PSIDTS)
Provides tools for generating and editing images, analyzing files (video, PDF, images, documents), and conducting text chats using Google Gemini models, with support for multi-turn conversations and auto-removal of watermarks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gemini-webapi-mcp generate an image of a cat in watercolor style"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Возможности
Генерация изображений по текстовому описанию (Nano Banana 2 с поддержкой пропорций)
2x разрешение — автоматически скачивает upscaled-версию (2048x2048 → 2816x1536 и выше)
Редактирование изображений — отправьте картинку + промпт и получите изменённую версию
Анализ файлов — видео, изображения, PDF, документы
Текстовый чат с Gemini (Flash, Pro, Flash-Thinking)
Авто-удаление вотермарки — sparkle-метка Gemini убирается встроенным детерминированным Reverse Alpha Blending (без внешних бинарников, ML-моделей и скачиваний)
Авто-аутентификация через cookies из Chrome
Related MCP server: Nano Banana 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-mcp3. Добавьте 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.jsonWindows:
%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-mcp5. Проверьте
Запустите сервер вручную — если инициализация прошла без ошибок, всё работает:
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.
Gemini отвечает «Are you signed in?» или ошибкой 1096, хотя в Chrome вы залогинены? Сервер берёт cookies только с домена
.google.com(версия от 2026-09-21); если у вас старая версия, а в Chrome есть cookies национальных доменов Google (.google.com.bd,.google.co.uk…), обновите сервер.
Если автоопределение cookies не работает, задайте их вручную:
Откройте Chrome DevTools на gemini.google.com → Application → Cookies
Скопируйте значения
__Secure-1PSIDи__Secure-1PSIDTSДобавьте в 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"
}
}
}
}Переменные окружения
Переменная | Описание | По умолчанию |
| Значение cookie | авто из Chrome |
| Значение cookie | авто из Chrome |
| Язык ответов Gemini ( |
|
| Индекс Google-аккаунта (0, 1, 2, ...) |
|
Высокое разрешение (2x)
Сервер автоматически запрашивает у Google увеличенную версию сгенерированного изображения — тот же механизм, что использует кнопка "Download" в веб-интерфейсе Gemini. Google выполняет server-side upscale, и вы получаете изображение в 2x разрешении:
Модель | Нативное | 2x (скачивается) |
Flash-Thinking (16:9) | 1408x768 | 2816x1536 |
Flash-Thinking (9:16) | 768x1376 | 1536x2752 |
Flash-Thinking (1:1) | 1024x1024 | 2048x2048 |
Если 2x-версия недоступна (таймаут, ошибка сети), сервер автоматически использует нативное разрешение.
Удаление вотермарки
Gemini добавляет sparkle-метку (четырёхконечную звёздочку) в правый нижний угол сгенерированных изображений. Сервер убирает её встроенным reverse-alpha-вычитанием — original = (L − A·shape·255) / (1 − A·shape) — без внешних бинарников, ML-моделей и скачиваний.
Метка всегда стоит в одном из двух фиксированных угловых якорей — на отступе 96 px или 32 px от правого нижнего угла (абсолютные отступы, не зависят от разрешения; логотип 48 px, ×2 при 2x-upscale). Сервер не детектирует метку по порогу корреляции — это ненадёжно на ярком фоне, где слабая полупрозрачная звёздочка почти не контрастирует. Вместо этого он детерминированно обрабатывает оба якоря:
per-image прозрачность — сила метки оценивается из самого кадра (
L = bg + A·shape·(255−bg), least-squares); на пустом якореA ≈ 0, поэтому вычитание становится no-op;reverse-alpha в позиции якоря;
self-check по |corr| — вычитание принимается, только если оно уменьшает корреляцию с формой звезды; иначе откатывается. Навредить пустому, текстурному или цветному-контентному якорю невозможно.
Подход не содержит ни одной захардкоженной «под разрешение» величины, поэтому работает на любом нативном разрешении и соотношении сторон — на светлом, тёмном и цветном фоне.
Единственный калиброванный инвариант — форма звезды в src/gemini_webapi_mcp/assets/wm_alpha_edit.npy. Чтобы временно отключить удаление (получить «сырой» водяной знак), задайте GEMINI_WM_KEEP=1.
Инструменты
Инструмент | Описание |
| Генерация новых или редактирование существующих изображений |
| Анализ файлов — видео, изображения, PDF, документы |
| Анализ URL — YouTube-видео, веб-страницы, статьи |
| Текстовый чат (одиночный или multi-turn) |
| Начать multi-turn сессию |
| Переинициализация клиента при ошибках авторизации |
Модели
Модель | По умолчанию для | Примечание |
| чат, анализ файлов | Быстрая |
| генерация изображений | Nano Banana 2, поддержка пропорций |
| — | Альтернативная модель |
Примеры использования
После настройки MCP-конфига Claude сам вызывает нужные инструменты. Просто попросите в чате:
Задача | Что написать Claude |
Сгенерировать изображение | «Сгенерируй через Gemini кота в акварельном стиле» |
Отредактировать изображение | «Отредактируй через Gemini /path/to/cat.png — сделай кота серым» |
Итеративная правка | «Теперь сделай фон темнее» (в том же разговоре) |
Проанализировать видео | «Проанализируй через Gemini это видео: https://youtube.com/watch?v=...» |
Проанализировать файл | «Загрузи в Gemini /path/to/doc.pdf и сделай краткое резюме» |
Инструменты, которые 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-mcpLocal install:
git clone https://github.com/AndyShaman/gemini-webapi-mcp.git
cd gemini-webapi-mcp
uv sync
uv run gemini-webapi-mcp3. 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.jsonWindows:
%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-mcp5. 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-mcpThen 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.
Gemini answers "Are you signed in?" or error 1096 while Chrome is logged in? The server takes cookies from the
.google.comdomain only (since 2026-09-21); on an older version, cookies of Google country domains in Chrome (.google.com.bd,.google.co.uk…) break auth — update the server.
If cookie auto-detection fails, set them manually:
Open Chrome DevTools on gemini.google.com → Application → Cookies
Copy
__Secure-1PSIDand__Secure-1PSIDTSvaluesAdd 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
Variable | Description | Default |
| Cookie value | auto from Chrome |
| Cookie value | auto from Chrome |
| Gemini response language ( |
|
| Google account index (0, 1, 2, ...) |
|
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:
Model | Native | 2x (downloaded) |
Flash-Thinking (16:9) | 1408x768 | 2816x1536 |
Flash-Thinking (9:16) | 768x1376 | 1536x2752 |
Flash-Thinking (1:1) | 1024x1024 | 2048x2048 |
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:
per-image opacity — the mark's strength is fit from the frame itself (
L = bg + A·shape·(255−bg), least-squares); on an empty anchorA ≈ 0, so the subtraction is a no-op;reverse alpha-blend at the anchor;
|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
Tool | Description |
| Generate new or edit existing images |
| Analyze files — video, images, PDF, documents |
| Analyze URLs — YouTube videos, webpages, articles |
| Text chat (single or multi-turn) |
| Start a multi-turn session |
| Re-initialize client on auth errors |
Models
Model | Default for | Notes |
| chat, file analysis | Fast |
| image generation | Nano Banana 2, supports aspect ratios |
| — | Alternative model |
Usage Examples
Once configured, Claude calls the right tools automatically. Just ask in chat:
Task | What to tell Claude |
Generate an image | "Generate a watercolor cat with Gemini" |
Edit an image | "Edit /path/to/cat.png with Gemini — make the cat gray" |
Iterative refinement | "Now make the background darker" (same conversation) |
Analyze a video | "Analyze this video with Gemini: https://youtube.com/watch?v=..." |
Analyze a file | "Upload /path/to/doc.pdf to Gemini and summarize it" |
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.
Available Tools
6 toolsgemini_analyze_urlARead-only
Analyze a URL — YouTube videos, webpages, articles, etc.
Gemini can watch YouTube videos and read webpages, then answer questions about their content.
Args: url: The URL to analyze (YouTube, article, webpage, etc.). prompt: Question or instruction about the content (e.g. 'Summarize this video', 'What are the key points?'). model: Model name. Defaults to gemini-3.0-flash.
Returns: Gemini's analysis of the URL content.
Inputs: url (required), prompt, model. Returns: result
gemini_chatARead-only
Send a text prompt to Google Gemini and get a response.
Args: prompt: The text prompt to send to Gemini. model: Model name (e.g. 'gemini-3.0-flash', 'gemini-3.0-pro', 'gemini-3.0-flash-thinking'). Defaults to gemini-3.0-flash. session_id: Optional session ID from gemini_start_chat for multi-turn conversation with context.
Returns: Gemini's text response. When using flash-thinking model, also includes the model's reasoning process.
Inputs: prompt (required), model, session_id. Returns: result
gemini_generate_imageA
Generate or edit images with Gemini.
Without files: generates a new image from the text prompt. With files: edits/transforms the provided image(s) based on the prompt.
Pass conversation_id from a previous call to continue refining images in the same conversation thread (e.g. "make it more dramatic", "add rain"). You can also use a cid from the Gemini web URL (gemini.google.com/app/{cid}).
Images are saved to ~/Pictures/gemini/ and full file paths are returned.
Args: prompt: Description of the image to generate, or editing instruction (e.g. 'change the background to blue', 'make it a cartoon'). model: Model name. Defaults to gemini-3.0-flash-thinking (Nano Banana 2, supports non-square aspect ratios). files: Optional list of file paths to images to edit/transform. conversation_id: Optional list of [cid, rid, rcid] from a previous gemini_generate_image response to continue the conversation. Passing just [cid] (from browser URL) also works.
Returns: JSON with generated image paths, conversation_id for continuation, or an error message.
Inputs: prompt (required), model, files, conversation_id. Returns: result
gemini_resetAIdempotent
Re-initialise the Gemini client (refresh cookies, clear state).
Use this when you get authentication errors or want a fresh session.
Returns: Confirmation message or error.
Inputs: no named parameters. Returns: result
gemini_start_chatA
Start a new multi-turn chat session with Gemini.
The session maintains conversation history so follow-up messages have full context. Pass the returned session_id to gemini_chat.
Args: model: Model name for this session. Defaults to gemini-3.0-flash.
Returns: JSON with session_id to use in subsequent gemini_chat calls.
Inputs: model. Returns: result
gemini_upload_fileARead-only
Upload a file (image, PDF, document, video) to Gemini and ask a question about it.
Args: file_path: Absolute path to the file to upload. prompt: Question or instruction about the file (e.g. 'What is shown in this image?'). model: Model name. Defaults to gemini-3.0-flash.
Returns: Gemini's text response about the uploaded file.
Inputs: file_path (required), prompt, model. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a unique function: analyzing URLs, chatting, generating images, resetting the client, starting multi-turn sessions, and uploading files. There is no overlap or ambiguity in their purposes.
All tools use a consistent 'gemini_' prefix and snake_case, but there is slight inconsistency in verb vs. verb_noun patterns (e.g., 'gemini_chat' vs 'gemini_start_chat'). The naming is mostly predictable and descriptive.
With 6 tools, the set is well-scoped without being too few or too many. Each tool serves a distinct purpose, covering core interactions with Gemini.
The tool set covers all major interaction modes: text chat, image generation, URL analysis, file upload, session management, and client reset. Minor gaps like model listing or conversation history management are non-essential.
Maintenance
Related MCP Connectors
MCP server for Google Veo AI video generation
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for Qwen Image 3 AI image generation
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for Google Gemini image generation, editing, and processing, with two tools and no bloat.21,017 npm2MIT
- AlicenseAqualityCmaintenanceMCP server for Google Gemini image generation with configurable model support, enabling text-to-image generation, image editing, and iterative refinement.640MIT
- AlicenseAqualityDmaintenanceMCP server for generating and editing images using Google Gemini API, with support for multi-turn iterative refinement.3135 npmMIT
- AlicenseAqualityDmaintenanceMCP server for AI image generation and editing using Google Gemini image models.71,647 npmMIT