# 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:**

```json
{
  "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:**

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

**Example — image reference:**

```json
{
  "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`:

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

### VS Code

Add to your `.vscode/mcp.json`:

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

### MCP Inspector

Test your server with the MCP Inspector:

```bash
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](https://github.com/modelcontextprotocol/typescript-sdk)
- Powered by [Google Vertex AI](https://cloud.google.com/vertex-ai)
- Uses [Express v5](https://expressjs.com/)