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.
- π― 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
git clone https://github.com/realcoding2003/vertex-ai-imagen-mcp.git
cd vertex-ai-imagen-mcp
pip install -r requirements.txt
- Create/select a project in Google Cloud Console
- Enable Vertex AI API
- Create a service account and download key file (see detailed guide below)
-
Configuration file location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
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"
}
}
}
}
- Restart Claude Desktop
After restarting Claude Desktop: "Generate a beautiful sunset landscape image"
git clone https://github.com/realcoding2003/vertex-ai-imagen-mcp.git
cd vertex-ai-imagen-mcp
pip install -r requirements.txt
-
Access Google Cloud Console
- Log in to Google Cloud Console
- Select an existing project or create a new one
-
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
-
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
- Service account name:
- Click "Create and Continue"
-
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"
-
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
-
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
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.
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
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
- Completely close Claude Desktop
- Restart Claude Desktop
- If a π§ icon appears in the bottom left, the MCP server has been successfully connected
After restarting Claude Desktop, you can generate images like this:
Ask Claude: "Generate a beautiful sunset landscape image"
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"
Ask Claude: "Generate a beautiful landscape image and save it in
/Users/username/Pictures/AI_Images folder with the name 'landscape.png'"
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"
python mcp_server.py
Generate images from text prompts
Required Parameters:
prompt
(string): Text prompt for image generation
Optional Parameters:
negative_prompt
(string): Content to avoidcount
(integer, 1-4): Number of images to generateaspect_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 resultssafety_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 available Imagen 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 |
β 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
β 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
β Project ID is not set
Solution:
- Set the
GOOGLE_CLOUD_PROJECT
environment variable - Check the project ID in Claude Desktop configuration
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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Create a Pull Request
This project is licensed under the MIT License. See the LICENSE file for details.
- 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
If you encounter any issues or have questions, please create an issue on GitHub Issues.
Made with β€οΈ by Kevin Park