Open Google Image Generator MCP

This project is a Model Context Protocol (MCP) server that exposes Google Cloud Vertex AI and Google GenAI SDK capabilities—Gemini (Nano Banana) image models, Gemini 3.x / 4 text models, Veo, Lyria, and Gemini TTS—to MCP-compatible clients. Built with the MCP Python SDK (FastMCP on mcp 1.x, MCPServer on mcp 2.x — both supported).

Current version: 3.3.0 — Image generation migrated from the shut-down Imagen 4 to the Gemini image family (gemini-3.1-flash-lite-image, gemini-3.1-flash-image, gemini-nano-banana-2.1, gemini-3-pro-image) served from the Vertex AI global endpoint; Gemini 3.8 Flash / 4 Argon text models; Gemini 3.8 TTS with all 30 prebuilt voices; Lyria 3.5; mcp 2.x compatibility.

Features & Tools

Image Tools

Tool	Description	Backend
`tool_generate_image`	Text-to-image generation. Supports aspect ratio, multiple images, and WebP/AVIF output. Negative prompt / seed / watermark / GCS output apply to legacy Imagen IDs only	Gemini image (`gemini-3.1-flash-lite-image`)
`tool_edit_image`	Mask-guided inpaint/outpaint, background swap, product image, and prompt-driven edit (mask is sent to Gemini as a reference image). See Edit modes below	Gemini image (`gemini-3.1-flash-image`) ⁴
`tool_transform_image`	Free-form `image + text → image` transformation: style transfer, scene rewriting, multi-reference composition	Gemini image (`gemini-3.1-flash-image`)
`tool_analyze_image`	Multimodal image understanding and Q&A. Supports `thinking_level` (MINIMAL/LOW/MEDIUM/HIGH) and `media_resolution` (LOW/MEDIUM/HIGH/ULTRA_HIGH)	Gemini (`gemini-3.8-flash`)
`tool_upscale_image`	Upscale to `2K` or `4K` (`target_resolution`), keeping the aspect ratio	Gemini image (`gemini-3.1-flash-image`) ⁴
`tool_remove_background`	Remove the background and save a transparent PNG. Optional `subject` (what to keep) and `key_color` (`green`/`blue`/`magenta`)	Gemini image + local chroma key ⁴
`tool_batch_generate`	Parallel batch text-to-image generation (up to 10 prompts, max 4 concurrent). All tiers supported	Gemini image
`tool_run_pipeline`	Sequential multi-step image processing pipeline (generate → edit → transform → …)	Mixed

⁴ These three tools used Imagen until v3.3.0. As of 2026-10-16 every Imagen model (imagen-3.0-capability-001, imagen-4.0-*, imagen-4.0-upscale-preview) returns HTTP 404 on Vertex AI in us-central1, us-west1, us-east4, europe-west4 and global (and Imagen 4 was shut down on the Gemini API on 2026-08-17), so they now run on Gemini image models. Gemini cannot emit an alpha channel, so tool_remove_background asks the model to paint everything except the subject in a flat chroma-key colour and keys it out locally with Pillow. Gemini edits are instruction-guided, not pixel-exact: content outside the mask is preserved closely but not bit-for-bit. Legacy imagen-* IDs are still accepted as model_name.

Video Tools

Tool	Description	Backend
`tool_generate_video`	Text-to-video generation. Supports `audio_enabled` for Veo 3+	Veo (`veo-3.1-fast-generate-001`) ⁵
`tool_image_to_video`	Animate a still image into video. Supports optional `last_frame_path` for first+last frame mode	Veo ⁵
`tool_extend_video`	Extend an existing video clip by 4, 6, or 8 seconds	Veo ⁵
`tool_video_object_edit`	Insert or remove an object in a video via `operation` (`insert`/`remove`) and `prompt`	Veo ⁵
`tool_analyze_video`	Video understanding and Q&A (max 20MB; mp4, mov, avi, webm, mkv)	Gemini GenAI SDK

⁵ The four Veo tools are still placeholder stubs: they validate input and write a text placeholder to the output path instead of calling Veo. Note that Veo 3.1 is served from us-central1 and global but returns 404 in other regions such as us-west1.

Audio Tools

Tool	Description	Backend
`tool_generate_speech`	Text-to-speech with any of the 30 prebuilt Gemini voices (Kore, Puck, Zephyr, Charon, Aoede, …). Supports `model_tier` (fast/quality). Outputs WAV	Gemini TTS (`gemini-3.8-flash-lite-tts` / `gemini-3.8-flash-tts`)
`tool_generate_music`	Music generation from a text prompt	Lyria 3.5 / Lyria 3 (GenAI SDK)

GenAI SDK Tools

Tool	Description	Backend
`tool_embed`	Text embeddings as float vectors	Gemini Embedding (`gemini-embedding-2` on Gemini API, `gemini-embedding-001` on Vertex AI)
`tool_live_generate`	Streaming text generation — response is accumulated and returned in full	Gemini (`gemini-3.5-flash-lite` / `gemini-3.8-flash` / `gemini-4-argon`)

Utility Tools

Tool	Description
`tool_list_available_models`	Live-probes every candidate model in the configured project (Gemini models on `GOOGLE_CLOUD_GEMINI_LOCATION`, Imagen on `GOOGLE_CLOUD_LOCATION`) and returns only those that respond (200/400 = reachable, 404 = excluded). Cached for the server process lifetime; pass `force_refresh=true` to rescan. Also reports available update versions.
`tool_upload_file`	Register a local file for use as a reference image in subsequent tool calls (e.g. `tool_transform_image`). Returns a `file_uri`.

Edit modes (`tool_edit_image`)

`edit_mode`	What it does	Mask required?
`EDIT_MODE_DEFAULT` (default)	Prompt-driven full-image edit, no mask	No
`EDIT_MODE_INPAINT_INSERTION`	Add an object into the masked region	Yes
`EDIT_MODE_INPAINT_REMOVAL`	Remove content in the masked region	Yes
`EDIT_MODE_OUTPAINT`	Extend the image beyond its original bounds	Yes
`EDIT_MODE_BGSWAP`	Swap the background	No
`EDIT_MODE_PRODUCT_IMAGE`	Product reference styling	No

All modes work with the Gemini image models (default gemini-3.1-flash-image; use gemini-3-pro-image for the most faithful edits). tool_edit_image also accepts model_tier.

When to use which "image + text → image" tool

Need	Use
Mask-guided inpaint/outpaint/BG-swap, or a specific edit mode	`tool_edit_image`
"Make it look like X" / style transfer / scene rewriting / multi-reference compositions	`tool_transform_image` (Gemini multimodal)

Model tiers

Most tools accept a model_tier parameter:

Tier	Description
`fast` (default)	Lowest latency, lowest cost
`balanced`	Quality / speed trade-off
`quality`	Higher quality, moderate latency
`ultra`	Maximum quality (Nano Banana Pro / Veo quality models)

Model resolution by tier and tool

Tier	`tool_generate_image` / `tool_batch_generate` / `tool_transform_image`	`tool_generate_video`
`fast`	`gemini-3.1-flash-lite-image`	`veo-3.1-fast-generate-001`
`balanced`	`gemini-3.1-flash-image`	`veo-3.1-fast-generate-001`
`quality`	`gemini-nano-banana-2.1`	`veo-3.1-generate-001`
`ultra`	`gemini-3-pro-image`	`veo-3.1-generate-001`

tool_edit_image and tool_remove_background use the same tier mapping. tool_upscale_image needs 2K/4K output, so its fast/balanced tiers use gemini-3.1-flash-image (the lite model is 1K-only); quality → gemini-nano-banana-2.1, ultra → gemini-3-pro-image. tool_run_pipeline applies the same per-tool mappings.

GenAI SDK tools (tool_live_generate, tool_analyze_video, tool_generate_speech, tool_embed):

Tier	`tool_live_generate` / `tool_analyze_video`	`tool_generate_speech`	`tool_embed`
`fast`	`gemini-3.5-flash-lite`	`gemini-3.8-flash-lite-tts`	`gemini-embedding-2` / `gemini-embedding-001` ²
`balanced`	`gemini-3.8-flash`	—	—
`quality`	`gemini-4-argon` ¹	`gemini-3.8-flash-tts`	—

¹ gemini-4-argon has no Gemini API free tier (quota limit 0) — it needs a billed key or Vertex AI. ² gemini-embedding-2 is used with a Gemini API key; gemini-embedding-001 with Vertex AI ADC.

Model IDs verified on 2026-10-16 against both catalogs. gemini-2.5-pro/flash/flash-lite retire on Vertex AI on 2026-10-20 and are no longer used as defaults.

Model availability: Vertex AI vs. Gemini API

Google exposes models through two separate endpoints with different model catalogs:

Endpoint	Auth	Image models	Text/speech models
Vertex AI (`aiplatform.googleapis.com`, `global` location)	ADC / Service Account	`gemini-3.1-flash-lite-image`, `gemini-3.1-flash-image`, `gemini-nano-banana-2.1`, `gemini-3-pro-image`, `gemini-2.5-flash-image`	`gemini-4-argon`, `gemini-3.8-flash`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3.1-flash-lite`, `gemini-3.8-flash-tts`, `gemini-3.8-flash-lite-tts`
Gemini API (`generativelanguage.googleapis.com`)	`GOOGLE_CLOUD_API_KEY` / `GOOGLE_GENAI_API_KEY`	same Gemini image family	same text/TTS models plus `lyria-3.5` (Gemini API only)

³ The Gemini 3.x image models (gemini-3-pro-image, gemini-3.1-flash-lite-image, gemini-nano-banana-2.1) are served by Vertex AI only from the global location — verified on 2026-10-16: they return HTTP 404 from us-west1 and HTTP 400 (exists) from global. The same holds for gemini-4-argon, gemini-3.8-flash, gemini-3.5-flash(-lite), gemini-3.1-flash-lite and the 3.8 TTS models. This server therefore sends every Gemini :generateContent call to GOOGLE_CLOUD_GEMINI_LOCATION (default global), and keeps Imagen/Veo on GOOGLE_CLOUD_LOCATION.

Sources:

Gemini API model catalog: https://ai.google.dev/gemini-api/docs/models.md.txt

Gemini API deprecations: https://ai.google.dev/gemini-api/docs/deprecations

Vertex AI model catalog: https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/google-models.md.txt

Vertex AI model versions & retirements: https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/model-versions

Vertex AI available models (live probe): run tool_list_available_models in your project

Output formats

tool_generate_image, tool_edit_image, tool_transform_image, and tool_upscale_image accept a save_format / output_format parameter:

Format	Notes
`PNG` (default)	Lossless
`JPEG`	Smaller files, lossy. `compression_quality` (0-100, default 85) applies only to JPEG
`WEBP`	Modern lossless/lossy, wide browser support
`AVIF`	Best compression, requires `Pillow>=10`

Error handling

All tools return a uniform error shape:

{
  "success": false,
  "error": {
    "code": 404,
    "model": "gemini-9.9-nonexistent",
    "endpoint": ":generateContent",
    "message": "Publisher Model `...` is not found.",
    "hint": "Model '...' not found in project '...' / location '...'. Try: gemini-3.1-flash-image.",
    "docs_url": "https://docs.cloud.google.com/...",
    "log_path": ".../logs/vertex_ai_mcp.log",
    "duration_s": 0.42
  }
}

HTTP code	What you'll see in `error.hint`
400	Vertex's parameter-validation message verbatim
401	"Run `gcloud auth application-default login` and retry."
403	IAM role hint (`roles/aiplatform.user`) + Vertex AI API enablement check
404	Live alternatives from the probe cache (`tool_list_available_models`)
429	`Retry after N` (from `Retry-After` header) + quota-increase pointer
500/502/503/504	"Safe to retry once"
`TIMEOUT`	After 90s — suggests a `-fast-` variant
`VALIDATION`	Client-side validation failure (mask missing, file not found, etc.); no HTTP call is made

Full request/response logs are written to logs/vertex_ai_mcp.log.

Resources & Prompts

Local Resources (local://outputs/{filename}): Generated and processed media files are exposed as MCP resources for seamless display in MCP clients (Claude Desktop, Cursor, etc.).
Pre-built Prompts: Includes specialized prompt templates for character_design, logo_concept, and UI_UX_mockup.

Prerequisites & Resources

Python 3.10 or newer
Google Cloud Account with an active project
Vertex AI API enabled in your project
Google Cloud CLI (gcloud) installed and configured

For GenAI SDK tools (tool_embed, tool_analyze_video, tool_generate_speech, tool_live_generate, tool_generate_music), you additionally need one of:

A Cloud API Key (GOOGLE_CLOUD_API_KEY) — created in GCP Console, uses your existing GCP billing. Enables newer models like gemini-3.5-flash. (Recommended)
A Gemini API key (GOOGLE_GENAI_API_KEY) — from AI Studio, separate billing.
Vertex AI ADC — set GOOGLE_GENAI_BACKEND=vertexai, uses gcloud auth application-default login.
Service Account JSON (GOOGLE_APPLICATION_CREDENTIALS) — see below.

Cloud API Key setup: Run gcloud services enable generativelanguage.googleapis.com apikeys.googleapis.com then gcloud services api-keys create --display-name="GeminiKey". The key string appears in the command output — copy it directly to .env.

Installation & Setup

Option A: Install from PyPI

pip install open-google-image-generator-mcp

Option B: Clone the Repository

git clone https://github.com/miracorhan/OpenGoogleImageGeneratorMCP.git
cd OpenGoogleImageGeneratorMCP
pip install -r requirements.txt

Authentication

Choose one of the following methods:

Option A — User account (interactive login):

gcloud auth application-default login

Opens a browser. Use an account that has access to your Google Cloud project.

Option B — Service Account JSON key:

# Download key: GCP Console → IAM & Admin → Service Accounts → Keys → Add Key → JSON
# Required role: Vertex AI User (roles/aiplatform.user)

Set in .env:

GOOGLE_APPLICATION_CREDENTIALS=C:\path\to\service-account-key.json

Both vertex_ai_tools (Imagen, Veo, Lyria) and genai_tools (embed, speech, video analysis, live) pick up the SA JSON automatically. No gcloud CLI required when using a service account key.

Environment Configuration

Create a .env file in the project root:

# Required
GOOGLE_CLOUD_PROJECT=your-google-cloud-project-id
GOOGLE_CLOUD_LOCATION=us-central1

# Optional: location for Gemini :generateContent calls (Gemini 3.x image/text
# models are served from `global` only). Imagen/Veo keep GOOGLE_CLOUD_LOCATION.
# GOOGLE_CLOUD_GEMINI_LOCATION=global

# Output directory for generated media
DEFAULT_OUTPUT_DIR=./outputs

# --- GenAI SDK (for embed, speech, live, music, video-analysis tools) ---
# Option A: Cloud API Key (recommended — uses GCP billing, enables gemini-3.5-flash)
# Create: gcloud services enable generativelanguage.googleapis.com apikeys.googleapis.com
#         gcloud services api-keys create --display-name="GeminiKey"
GOOGLE_CLOUD_API_KEY=AIza...

# Option B: Gemini API key (AI Studio, separate billing, free tier available)
# GOOGLE_GENAI_BACKEND=gemini_api
# GOOGLE_GENAI_API_KEY=AIza...

# Option C: Vertex AI ADC (no key needed, uses gcloud auth application-default login)
# GOOGLE_GENAI_BACKEND=vertexai

# Option D: Service Account JSON key (no gcloud CLI required)
# Download: GCP Console → IAM & Admin → Service Accounts → Keys → Add Key → JSON
# Required role: Vertex AI User (roles/aiplatform.user)
# GOOGLE_APPLICATION_CREDENTIALS=C:\path\to\service-account-key.json

# --- Advanced Vertex AI Authentication (Optional) ---
# Direct OAuth 2.0 Access Token
# GOOGLE_ACCESS_TOKEN=ya29.a0AfB_by...

# Service Account Impersonation
# IMPERSONATE_SERVICE_ACCOUNT=your-service-account@your-project.iam.gserviceaccount.com

Usage

Running as a Standalone Script

python mcp_server.py

Integrating with MCP Clients

For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "OpenGoogleImageGenerator": {
      "command": "python",
      "args": ["/absolute/path/to/OpenGoogleImageGeneratorMCP/mcp_server.py"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-google-cloud-project-id",
        "GOOGLE_CLOUD_LOCATION": "us-central1",
        "GOOGLE_GENAI_API_KEY": "AIza..."
      }
    }
  }
}

Replace /absolute/path/to/your/... with the actual path, and use the correct Python executable if using a virtual environment.

Example prompts

"Generate an image of a futuristic city at sunset."
"Edit this banner — add a glowing cyan halo around the logo." (tool_edit_image, EDIT_MODE_DEFAULT)
"Transform this photo into a hand-drawn pencil sketch." (tool_transform_image)
"Remove the background from the image I just generated."
"Analyze this image and tell me what objects are present."
"Generate 8 product shots in parallel with different backgrounds." (tool_batch_generate)
"Run a pipeline: generate → remove background → upscale." (tool_run_pipeline)
"Convert this text to speech using the Kore voice." (tool_generate_speech)
"Generate a 30-second ambient music track." (tool_generate_music)
"Embed this sentence for semantic search." (tool_embed)
"Animate this product photo into a 5-second video." (tool_image_to_video)
"Generate a video of a sunset with audio." (tool_generate_video, audio_enabled=true)

Troubleshooting

Symptom	Cause	Fix
`RefreshError` / "Reauthentication needed"	ADC token expired	`gcloud auth application-default login` or switch to SA JSON
`available: {}` from `tool_list_available_models`	Same ADC expiry, probe skipped	Re-authenticate (above)
`403 PERMISSION_DENIED` with SA JSON	Service account missing role	Grant `roles/aiplatform.user` to the service account
`FileNotFoundError` for SA JSON	Wrong path in `GOOGLE_APPLICATION_CREDENTIALS`	Use an absolute path; forward slashes or escaped backslashes
`401 UNAUTHENTICATED` with `GOOGLE_CLOUD_API_KEY`	Key used with Vertex AI endpoint (rejects keys)	Ensure `GOOGLE_GENAI_BACKEND` is not set to `vertexai` when using a Cloud API key
`403 PERMISSION_DENIED` — "Gemini API has not been used"	`generativelanguage.googleapis.com` not enabled	`gcloud services enable generativelanguage.googleapis.com`
`400 INVALID_ARGUMENT` — "API key not valid" even with a brand-new key	Google's key-validation error is identical whether the key is dead or `generativelanguage.googleapis.com` just isn't enabled on that project — the message doesn't distinguish the two	Confirm with `gcloud services list --project=YOUR_PROJECT --filter="config.name:generativelanguage.googleapis.com"`; if missing, `gcloud services enable generativelanguage.googleapis.com --project=YOUR_PROJECT` and allow a few minutes for propagation before retrying
`403 PERMISSION_DENIED` — "API Keys API disabled"	`apikeys.googleapis.com` blocked by org policy	`gcloud services enable apikeys.googleapis.com`
`tool_generate_speech` / `tool_embed` / `tool_live_generate` / `tool_analyze_video` return `404 NOT_FOUND` under `GOOGLE_GENAI_BACKEND=vertexai`	The TTS-preview, live-preview, and embedding-preview models used by these tools are not published to the Vertex AI publisher catalog — Vertex AI/ADC is not a usable fallback for them, unlike image models	Use `GOOGLE_CLOUD_API_KEY` or `GOOGLE_GENAI_API_KEY` (Gemini API endpoint) for these four tools specifically
Worried a GenAI SDK call will charge your Cloud Billing / free-trial credit	Once billing is enabled on a project, the Gemini API free tier is gone entirely for that project — every call becomes billable from the first token, and some promotional/free-trial credits explicitly exclude Gemini API usage regardless	For risk-free testing, create a separate GCP project with no billing account attached at all and generate its AI Studio key there (`GOOGLE_GENAI_API_KEY`); verify with `gcloud billing projects describe YOUR_PROJECT` → `billingEnabled: false`. Keep your billed project for Vertex AI (Imagen/Veo/Lyria) only
Edited `.env` but the exact same auth error keeps happening	`config.py` loads `.env` once at process start and `genai_tools._genai_client` is cached for the process lifetime — editing the file does not affect an already-running server	Reconnect the MCP server (`/mcp` → reconnect, or restart the client) after any `.env` change
`404 NOT_FOUND` for `text-embedding-004`	`text-embedding-004` was shut down on the Gemini API (2026-01-14) and retires on Vertex AI on 2027-04-01	Omit `model` to use the default (`gemini-embedding-2` / `gemini-embedding-001`)
`404 NOT_FOUND` for `gemini-3-pro-image`, `gemini-3.1-flash-lite-image` or `gemini-nano-banana-2.1` on Vertex AI	These models are served from the `global` location only	Leave `GOOGLE_CLOUD_GEMINI_LOCATION` unset (defaults to `global`)
`404` / `NOT_FOUND` for `imagen-4.0-*`	Imagen 4 has been shut down (Gemini API: 2026-08-17)	Use `model_tier` or a Gemini image model (`gemini-3.1-flash-lite-image`, `gemini-nano-banana-2.1`, `gemini-3-pro-image`)
`400 INVALID_ARGUMENT` mentioning `thinking_budget` / `MINIMAL` on `gemini-3.8-flash` / `gemini-4-argon`	These models only accept `thinkingLevel` LOW/MEDIUM/HIGH	Handled automatically by `tool_analyze_image` since v3.3.0 — update the server
`429 RESOURCE_EXHAUSTED` with `limit: 0` for `gemini-4-argon`	The model has no Gemini API free tier	Use a billed key, Vertex AI, or a lower tier (`fast` / `balanced`)
`ModuleNotFoundError: No module named 'mcp.server.fastmcp'`	Server older than v3.3.0 installed with `mcp` 2.x	Update the server (v3.3.0 supports both `mcp` 1.x and 2.x)
`404 NOT_FOUND` for a model	Model not available in your project/region	Run `tool_list_available_models` and pick from `available` list
`gcloud api-keys` command not found	Wrong command prefix	Use `gcloud services api-keys list/create/delete`

Security: The Cloud API Key string appears in plaintext in gcloud services api-keys create output. Copy it directly to .env — never paste it into a chat, commit, or log. Revoke a leaked key immediately with gcloud services api-keys delete KEY_ID.

Author & License

Developer: Mirac Orhan (mirac.orhan@gmail.com)
License: MIT License (Open Source — Free for everyone to use, modify, and distribute)

Name		Name	Last commit message	Last commit date
docs/superpowers		docs/superpowers
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
config.py		config.py
discovery.py		discovery.py
format_converter.py		format_converter.py
genai_tools.py		genai_tools.py
mcp_server.py		mcp_server.py
model_registry.py		model_registry.py
pipeline.py		pipeline.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
update.py		update.py
vertex_ai_tools.py		vertex_ai_tools.py

Navigation Menu

Repository navigation

About

Repository files navigation

Open Google Image Generator MCP

Features & Tools

Image Tools

Video Tools

Audio Tools

GenAI SDK Tools

Utility Tools

Edit modes (`tool_edit_image`)

When to use which "image + text → image" tool

Model tiers

Model resolution by tier and tool

Model availability: Vertex AI vs. Gemini API

Output formats

Error handling

Resources & Prompts

Prerequisites & Resources

Installation & Setup

Option A: Install from PyPI

Option B: Clone the Repository

Authentication

Environment Configuration

Usage

Running as a Standalone Script

Integrating with MCP Clients

Example prompts

Troubleshooting

Author & License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Open Google Image Generator MCP

Features & Tools

Image Tools

Video Tools

Audio Tools

GenAI SDK Tools

Utility Tools

Edit modes (tool_edit_image)

When to use which "image + text → image" tool

Model tiers

Model resolution by tier and tool

Model availability: Vertex AI vs. Gemini API

Output formats

Error handling

Resources & Prompts

Prerequisites & Resources

Installation & Setup

Option A: Install from PyPI

Option B: Clone the Repository

Authentication

Environment Configuration

Usage

Running as a Standalone Script

Integrating with MCP Clients

Example prompts

Troubleshooting

Author & License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Edit modes (`tool_edit_image`)