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—Imagen, Gemini, Veo, Lyria, and Chirp models—to MCP-compatible clients. Built with the FastMCP framework.

Current version: 3.0.0 — Full GenAI SDK integration (embed, speech, video analysis, live generation), WebP/AVIF format support, multi-tier model selection, parallel batch generation, sequential pipeline engine, and comprehensive video tools.

Features & Tools

Image Tools

| Tool | Description | Backend | |---|---|---| | tool_generate_image | Text-to-image generation. Supports aspect ratio, negative prompt, seed, watermark, GCS output, and WebP/AVIF output | Imagen 4 (imagen-4.0-fast-generate-001) | | tool_edit_image | Mask-based inpaint/outpaint, background swap, product image, and prompt-driven edit. See Edit modes below | Imagen 3 Capability (imagen-3.0-capability-001) | | tool_transform_image | Free-form image + text → image transformation: style transfer, scene rewriting, multi-reference composition | Gemini multimodal (gemini-2.5-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 Vision (gemini-2.5-flash) | | tool_upscale_image | Upscale low-resolution images | Imagen | | tool_remove_background | Remove background via EDIT_MODE_BGSWAP | Imagen | | tool_batch_generate | Parallel batch text-to-image generation (up to 10 prompts, max 4 concurrent). balanced tier not supported for batch | Imagen | | tool_run_pipeline | Sequential multi-step image processing pipeline (generate → edit → transform → …) | Mixed |

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 |

Audio Tools

| Tool | Description | Backend | |---|---|---| | tool_generate_speech | Text-to-speech with voice selection (Aoede, Charon, Fenrir, Kore, Puck). Supports model_tier (fast/quality). Outputs WAV | Gemini TTS (gemini-2.5-flash-preview-tts / gemini-2.5-pro-preview-tts) | | tool_generate_music | Music generation from a text prompt | Lyria 2 / Lyria 3 (GenAI SDK) |

GenAI SDK Tools

| Tool | Description | Backend | |---|---|---| | tool_embed | Text embeddings as float vectors | Gemini Embedding (text-embedding-004 on Vertex AI, gemini-embedding-2 on Gemini API) | | tool_live_generate | Streaming text generation — response is accumulated and returned in full | Gemini Live (gemini-2.5-flash / gemini-3.1-pro) |

Utility Tools

| Tool | Description | |---|---| | tool_list_available_models | Live-probes every candidate model in the configured project/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 |

Use imagen-3.0-capability-001 (default) for all of the above. The legacy imagen-3.0-generate-002 only supports EDIT_MODE_DEFAULT and does not accept a mask.

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

| Need | Use | |---|---| | Mask-based inpaint/outpaint/BG-swap with pixel precision | tool_edit_image (Imagen Capability) | | "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; routes to Gemini for image generation. Not supported for tool_batch_generate | | quality | Higher quality, moderate latency | | ultra | Maximum quality (Imagen 4 Ultra / Veo quality models) |

Model resolution by tier and tool

| Tier | tool_generate_image | tool_transform_image | tool_generate_video | |---|---|---|---| | fast | imagen-4.0-fast-generate-001 | gemini-2.5-flash-image | veo-3.1-fast-generate-001 | | balanced | gemini-2.5-flash-image | gemini-2.5-flash-image | veo-3.1-fast-generate-001 | | quality | imagen-4.0-generate-001 | gemini-2.5-pro-image | veo-3.1-generate-001 | | ultra | imagen-4.0-ultra-generate-001 | gemini-2.5-pro-image | veo-3.1-generate-001 |

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-2.5-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

1. Python 3.9 or newer
2. Google Cloud Account with an active project
3. Vertex AI API enabled in your project
4. 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 either:

• A Gemini API key (GOOGLE_GENAI_API_KEY), or
• Vertex AI ADC credentials with GOOGLE_GENAI_BACKEND=vertexai

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 (Critical Step)

The server uses Google Cloud Application Default Credentials (ADC):

gcloud auth application-default login

This opens a browser for login. Use an account with access to your Google Cloud project.

Environment Configuration

Create a .env file in the project root:

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

# Output directory for generated media
DEFAULT_OUTPUT_DIR=./outputs

# --- GenAI SDK (for embed, speech, live, music, video-analysis tools) ---
# Option A: Gemini API key (free tier available)
GOOGLE_GENAI_API_KEY=AIza...

# Option B: Use Vertex AI backend (uses ADC above, no separate key needed)
GOOGLE_GENAI_BACKEND=vertexai

# --- 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)

Author & License

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