What is Vertex Ai Imagen Mcp

vertex-ai-imagen-mcp is a Model Context Protocol (MCP) server that integrates Google Cloud’s Vertex AI Imagen models to generate high-quality images from text prompts. It supports both interactive command-line interface (CLI) and MCP protocol modes.

Use cases

Use cases include generating artwork from creative prompts, creating marketing visuals based on product descriptions, enhancing game graphics with AI-generated images, and providing visual content for social media posts.

How to use

To use vertex-ai-imagen-mcp, you need to set up a Google Cloud service account with the Vertex AI API enabled. After cloning the repository and installing the required packages, configure the environment variables and run the server in standalone mode for testing.

Key features

Key features include support for the latest Imagen models, full MCP integration, a standalone interactive CLI mode, rich options for image generation (such as aspect ratios and negative prompts), built-in safety features like content filtering and watermarking, easy setup, and comprehensive documentation.

Where to use

vertex-ai-imagen-mcp can be used in various fields such as digital art creation, marketing, gaming, and any application requiring high-quality image generation from textual descriptions.

🎨 Vertex AI Imagen MCP Server

Languages: 🇰🇷 한국어

---

Model Context Protocol (MCP) Server for Google Cloud Vertex AI Imagen

This MCP server enables direct generation of high-quality AI images in Claude Desktop using the vertex-ai-imagen package.

✨ Key Features

• 🎯 Simple Setup: Streamlined architecture based on the vertex-ai-imagen package
• 🚀 Claude Desktop Integration: Seamless image generation through MCP
• 🎨 Multiple Model Support: Imagen 3.0, imagegeneration@006, and more
• 🔧 Flexible Options: Aspect ratios, image count, safety settings, etc.
• 🔒 Secure Authentication: Google Cloud Service Account based

🚀 Quick Start (5-minute Setup)

1️⃣ Project Installation

git clone https://github.com/realcoding2003/vertex-ai-imagen-mcp.git
cd vertex-ai-imagen-mcp
pip install -r requirements.txt

2️⃣ Google Cloud Authentication Setup

1. Create/select a project in Google Cloud Console
2. Enable Vertex AI API
3. Create a service account and download key file (see detailed guide below)

3️⃣ Claude Desktop Configuration

1. Configuration file location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add configuration content:

{
  "mcpServers": {
    "vertex-ai-imagen": {
      "command": "python",
      "args": [
        "/absolute/path/to/vertex-ai-imagen-mcp/mcp_server.py"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-actual-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/your-key-file.json"
      }
    }
  }
}

3. Restart Claude Desktop

4️⃣ First Image Generation Test

After restarting Claude Desktop: “Generate a beautiful sunset landscape image”

---

🛠️ Detailed Installation & Setup

1. Clone Repository

git clone https://github.com/realcoding2003/vertex-ai-imagen-mcp.git
cd vertex-ai-imagen-mcp

2. Install Dependencies

pip install -r requirements.txt

3. Google Cloud Setup

3.1 Google Cloud Project and API Activation

1. Access Google Cloud Console

   • Log in to Google Cloud Console
   • Select an existing project or create a new one

2. Enable Vertex AI API

   • Navigate to “APIs & Services” → “Library” from the left menu
   • Search for “Vertex AI API” and click on it
   • Click the “Enable” button to activate the API

   Or enable directly via this link

3.2 Service Account Creation and Key File Download

1. Create Service Account

   • Go to “IAM & Admin” → “Service Accounts” in Google Cloud Console
   • Click “Create Service Account”
   • Enter service account details:
     • Service account name: imagen-mcp (or your preferred name)
     • Service account ID: Auto-generated
     • Description: Service account for Imagen MCP Server
   • Click “Create and Continue”

2. Grant Permissions

   • In the “Grant this service account access to project” section
   • Select Vertex AI User role from the “Select a role” dropdown
   • Click “Continue”

3. Generate and Download Key File

   • Skip the “Grant users access to this service account” section and click “Done”
   • Click on the email address of the newly created service account
   • Go to the “Keys” tab
   • Click “Add Key” → “Create new key”
   • Select key type: JSON
   • Click “Create” and the JSON key file will be automatically downloaded

4. Store Key File in Safe Location

   # Example: macOS/Linux
   mkdir -p ~/.config/gcloud
   mv ~/Downloads/your-project-id-xxxxxx.json ~/.config/gcloud/imagen-mcp-key.json
   
   # Example: Windows
   mkdir %USERPROFILE%\.config\gcloud
   move %USERPROFILE%\Downloads\your-project-id-xxxxxx.json %USERPROFILE%\.config\gcloud\imagen-mcp-key.json
   

4. Environment Variable Setup

Set environment variables with the downloaded key file and project information:

macOS/Linux:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/imagen-mcp-key.json"

Windows (PowerShell):

$env:GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
$env:GOOGLE_APPLICATION_CREDENTIALS="$HOME\.config\gcloud\imagen-mcp-key.json"

💡 How to find Project ID: Use the ID displayed next to the project name at the top of Google Cloud Console.

🔧 Claude Desktop Configuration

Check Configuration File Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Edit Configuration File

Create/edit the claude_desktop_config.json file to register the MCP server:

{
  "mcpServers": {
    "vertex-ai-imagen": {
      "command": "python",
      "args": [
        "/absolute/path/to/vertex-ai-imagen-mcp/mcp_server.py"
      ],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-actual-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/your-key-file.json"
      }
    }
  }
}

⚠️ Important:

• All paths must be absolute paths
• Replace your-actual-project-id with your actual Google Cloud project ID
• Replace the key file path with the actual path to your downloaded JSON file

After Configuration

1. Completely close Claude Desktop
2. Restart Claude Desktop
3. If a 🔧 icon appears in the bottom left, the MCP server has been successfully connected

🚀 Usage

Using in Claude Desktop

After restarting Claude Desktop, you can generate images like this:

Ask Claude: "Generate a beautiful sunset landscape image"

Using Advanced Options

Ask Claude: "Generate an image of a cat traveling through space in 16:9 aspect ratio, 
create 2 images, use the imagen-3.0-fast-generate-001 model, 
and add 'blurry, low quality' as negative prompt"

Specifying Image Save Path

Ask Claude: "Generate a beautiful landscape image and save it in 
/Users/username/Pictures/AI_Images folder with the name 'landscape.png'"

Saving with Exact Filename

Ask Claude: "Generate a website hero image. Make it 16:9 aspect ratio, 
use the imagen-3.0-generate-001 model, and save it as 'hero.png' in 
/Users/kevinpark/Documents/projects/realcoding.github.io/assets/images/posts/ai-tutorial/ 
directory"

Interactive Mode (Without MCP)

python mcp_server.py

🎯 Available Tools

generate_image

Generate images from text prompts

Required Parameters:

• prompt (string): Text prompt for image generation

Optional Parameters:

• negative_prompt (string): Content to avoid
• count (integer, 1-4): Number of images to generate
• aspect_ratio (string): Aspect ratio (“1:1”, “3:4”, “4:3”, “16:9”, “9:16”)
• model (string): Model to use (default: “imagegeneration@006”)
• seed (integer): Seed value for reproducible results
• safety_setting (string): Safety filter level (default: “block_some”)
• save_path (string): Directory path to save images (if not specified, images are only displayed in Claude)
• filename (string): Exact filename (with or without extension). Using this option saves with the specified name without timestamp.
• filename_prefix (string): Filename prefix (default: “generated_image”). Only used when filename is not specified.

💡 Filename Behavior:

• When filename is specified: Saves with exact filename (adds _1,_2 etc. for multiple images)
• When filename is not specified: Saves as {filename_prefix}_{timestamp}_{number}.png format

list_models

List available Imagen models

🤖 Supported Models

Model Name	Speed	Quality	Use Case
imagegeneration@006	🟡 Medium	🟣 Excellent	General purpose
imagen-3.0-generate-001	🟡 Medium	🟣 Excellent	High-quality work
imagen-3.0-generate-002	🟡 Medium	🟣 Excellent	Latest high-quality
imagen-3.0-fast-generate-001	⚡ Fast	🟢 Good	Fast prototyping

🔍 Troubleshooting

Common Issues

1. Authentication Error

❌ Authentication failed: could not find default credentials

Solution:

• Check if GOOGLE_APPLICATION_CREDENTIALS environment variable is set correctly
• Verify that the service account key file exists and is readable

2. Permission Error

❌ 403 Forbidden: The caller does not have permission

Solution:

• Verify that the service account has the roles/aiplatform.user role
• Check if Vertex AI API is enabled

3. Project ID Error

❌ Project ID is not set

Solution:

• Set the GOOGLE_CLOUD_PROJECT environment variable
• Check the project ID in Claude Desktop configuration

📁 Project Structure

vertex-ai-imagen-mcp/
├── mcp_server.py              # Main MCP server
├── requirements.txt           # Python dependencies
├── .gitignore                # Git ignore file
├── README.md                 # Korean version
├── README_EN.md              # This file (English version)
├── LICENSE                   # MIT License
├── claude_desktop_config.json # Claude Desktop configuration example
└── examples/                 # Usage examples
    └── basic_usage.py        # Basic usage example

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🔗 Related Links

• vertex-ai-imagen package - Core AI image generation library
• Google Cloud Vertex AI - Official Vertex AI documentation
• Model Context Protocol - Official MCP website
• Claude Desktop - Claude Desktop application

❓ Questions & Support

If you encounter any issues or have questions, please create an issue on GitHub Issues.

---

Made with ❤️ by Kevin Park