MCP Google Vertex AI Server

A Model Context Protocol (MCP) server that provides AI-powered image and video generation capabilities using Google Vertex AI's Imagen and Veo models.

Features

• 🎨 Image Generation: Create AI images using Google's Imagen model
• 🎬 Video Generation: Generate AI videos using Google's Veo model
• 💾 Local Storage: Automatically save generated content to local server storage
• 🔒 Secure Configuration: Environment-based configuration for API credentials
• 🚀 Express v5: Built on the latest Express framework
• 📝 TypeScript: Fully typed for better developer experience
• ♻️ DRY Principles: Clean, maintainable, and reusable code architecture

Prerequisites

• Node.js 24.0.0 or higher
• Google Cloud Project with Vertex AI API enabled
• Service account credentials with appropriate permissions

MCP Tools

generate-image

Generate AI images using the configured Imagen model (set via VERTEX_AI_IMAGE_MODEL).

Parameters:

Parameter	Type	Default	Description
prompt	string	required	Text description of the image to generate
numberOfImages	number (1-8)	1	Number of images to generate
aspectRatio	1:1 | 3:4 | 4:3 | 9:16 | 16:9	1:1	Aspect ratio
imageSize	1K | 2K	2K	Output resolution
outputMimeType	image/png | image/jpeg	image/png	Output format
negativePrompt	string	—	Things to avoid in the image
guidanceScale	number (1-20)	—	How closely the model follows the prompt
seed	number	—	Random seed for reproducible results
enhancePrompt	boolean	false	Auto-enhance the prompt before generation

Example:

{
  "name": "generate-image",
  "arguments": {
    "prompt": "A serene mountain landscape at sunset with a lake",
    "aspectRatio": "16:9",
    "numberOfImages": 2
  }
}

generate-video

Generate AI videos using the configured Veo model (set via VERTEX_AI_VIDEO_MODEL).

Parameters:

Parameter	Type	Default	Description
prompt	string	required	Text description of the video to generate
numberOfVideos	number (1-4)	1	Number of videos to generate
durationSeconds	number (4-8)	8	Clip length in seconds (4, 6, or 8)
aspectRatio	16:9 | 9:16	16:9	Aspect ratio
resolution	720p | 1080p | 4K	1080p	Video resolution
seed	number	—	Random seed for reproducible results
negativePrompt	string	—	Things to avoid in the video
enhancePrompt	boolean	true	Auto-enhance the prompt before generation
generateAudio	boolean	false	Generate audio alongside the video
lastFrame	string	—	Image to use as the last frame (image-to-video)
referenceImages	array	—	Reference images to guide generation (see below)

Reference images (provide either a local file path, Cloud Storage URI, or public URL):

• Local file path: /path/to/image.png
• Cloud Storage URI: gs://my-bucket/image.jpg
• Public URL: https://cdn.example.com/image.jpg

Supported formats: JPEG, PNG. Maximum size: 10 MB.

referenceImages supports up to 3 ASSET images or 1 STYLE image.

Example — text to video:

{
  "name": "generate-video",
  "arguments": {
    "prompt": "A butterfly flying through a garden of flowers",
    "durationSeconds": 8,
    "aspectRatio": "16:9",
    "resolution": "1080p"
  }
}

Example — image reference:

{
  "name": "generate-video",
  "arguments": {
    "prompt": "The product spinning on a white background",
    "referenceImages": [
      {
        "image": "/path/to/product.png",
        "referenceType": "ASSET"
      }
    ]
  }
}

Connecting to MCP Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "google-vertex": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3005/mcp"]
    }
  }
}

VS Code

Add to your .vscode/mcp.json:

{
  "servers": {
    "google-vertex": {
      "type": "http",
      "url": "http://localhost:3005/mcp"
    }
  }
}

MCP Inspector

Test your server with the MCP Inspector:

npx @modelcontextprotocol/inspector

Then connect to: http://localhost:3005/mcp

Architecture

The server follows clean architecture principles with separation of concerns:

• Config Layer: Environment variable management and validation
• Service Layer: Vertex AI integration and storage management
• Tools Layer: Shared utilities (e.g. reference image resolution)
• Server Layer: MCP protocol implementation and Express server setup

Error Handling

The server includes comprehensive error handling:

• Graceful error responses for tool invocations
• Detailed error messages for troubleshooting
• Proper HTTP status codes

Performance Tips

• Use appropriate aspect ratios and resolutions for your use case
• Monitor Vertex AI quotas and billing
• Consider implementing request queuing for high-traffic scenarios

License

MIT

Acknowledgments

• Built with the Model Context Protocol SDK
• Powered by Google Vertex AI
• Uses Express v5