Open Google Image Generator MCP

This project is a Model Context Protocol (MCP) server that exposes Google Cloud Vertex AI capabilities—specifically Imagen 3 and Gemini Vision models—to MCP-compatible clients. It is built using the FastMCP framework.

Features & Tools

The server provides a comprehensive suite of MCP tools for interacting with Vertex AI:

• tool_list_available_models: Live-probes every candidate publisher model in the configured project/location and returns only the ones that actually respond (200/400 = reachable, 404 = excluded). Cached for the server process lifetime; pass force_refresh=true to rescan.

• tool_generate_image: Text-to-image generation via Imagen (default: imagen-4.0-fast-generate-001).

• tool_edit_image: Precision image editing via Imagen 3 Capability (imagen-3.0-capability-001). Supports mask-based inpaint/outpaint, background swap, product image, and mask-free prompt-driven edit. See Edit modes below.

• tool_transform_image: (new) Free-form image + text → image transformation via Gemini multimodal (gemini-2.5-flash-image). Use for style transfer, scene rewriting, or any natural-language image edit that doesn't need pixel-precise masking. Accepts optional additional reference images.

• tool_analyze_image: Multimodal image analysis via Gemini Vision (default: gemini-2.5-flash).

• tool_upscale_image: Upscales low-resolution images via Imagen.

• tool_remove_background: Removes background via Imagen EDIT_MODE_BGSWAP.

• tool_generate_video: Currently a forward-compatible stub for Veo 3.1.

Edit modes (tool_edit_image)

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

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

Error handling

All tools return a uniform error shape so MCP clients and direct Python callers see the same diagnostics:

{
  "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
  }
}

Full request/response logs are written to logs/vertex_ai_mcp.log (also surfaced in error.log_path).

Resources & Prompts

• Local Resources (local://outputs/{filename}): The server directly exposes generated and processed media files as MCP resources, allowing seamless display within your MCP client (like Claude Desktop or Cursor).

• Pre-built Prompts: Includes specialized prompt templates for character_design, logo_concept, and UI_UX_mockup to help you get the best results following Gemini 3 prompting guidelines.

Prerequisites & Resources

Before you begin, ensure you have the following resources and permissions set up:

1. Python: Python 3.9 or newer installed on your machine.

2. Google Cloud Account: An active Google Cloud account and project.

3. Vertex AI API: The Vertex AI API must be enabled in your Google Cloud Project.

4. Google Cloud CLI (gcloud): Installed and configured for authentication.

Installation & Setup

1. Clone the Repository

Navigate to the project directory in your terminal:

cd OpenGoogleImageGeneratorMCP

2. Install Dependencies

Install the required Python packages using pip:

pip install -r requirements.txt

3. Authentication (Critical Step)

The server uses Google Cloud Application Default Credentials (ADC). You must authenticate your local environment using the gcloud CLI:

gcloud auth application-default login

This command will open a browser window for you to log in to your Google account. Ensure you log in with an account that has access to your Google Cloud Project.

4. Environment Configuration

Create a .env file in the root of the project directory. This file configures the server with your specific Google Cloud details:

# Your Google Cloud Project ID (Required)
GOOGLE_CLOUD_PROJECT=your-google-cloud-project-id

# The Google Cloud region to use (e.g., us-central1, europe-west4)
GOOGLE_CLOUD_LOCATION=us-central1

# Directory where generated images/videos will be saved locally
DEFAULT_OUTPUT_DIR=./outputs

# --- Advanced Authentication Options (Optional) ---
# If you want to bypass Application Default Credentials, you can use one of these:

# 1. Direct OAuth 2.0 Access Token: 
# Useful if an upstream app manages tokens and passes them down.
# GOOGLE_ACCESS_TOKEN=ya29.a0AfB_by...

# 2. Service Account Impersonation:
# Useful for high-security environments where the default account assumes the role of a service account.
# IMPERSONATE_SERVICE_ACCOUNT=your-service-account@your-project.iam.gserviceaccount.com

Usage

Running as a Standalone Script

You can start the MCP server manually to verify it works without errors:

python mcp_server.py

Integrating with MCP Clients

To use this server, you need to configure your MCP client (such as Claude Desktop or Cursor) to launch this script.

For Claude Desktop (example claude_desktop_config.json):

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

Note: Make sure to replace /absolute/path/to/your/... with the actual path to the script, and configure the path to your python executable if you are using a virtual environment.

Once configured and the client is restarted, you can ask your AI assistant tasks like:

• "Generate an image of a futuristic city at sunset."

• "Edit this banner — add a glowing cyan halo around the logo." (uses tool_edit_image, EDIT_MODE_DEFAULT)

• "Transform this photo into a hand-drawn pencil sketch." (uses tool_transform_image)

• "Remove the background from the image I just generated."

• "Analyze this image and tell me what objects are present."

Author & License

• Developer: Mirac Orhan (mirac.orhan@gmail.com)

• License: MIT License (Open Source - Free for everyone to use, modify, and distribute)