@raihan0824/mcp-veo2/README.md

MCP server for generating videos with Google Veo2

# MCP Video Generation with Veo2

[![smithery badge](https://smithery.ai/badge/@mario-andreschak/mcp-video-generation-veo2)](https://smithery.ai/server/@mario-andreschak/mcp-video-generation-veo2)

This project implements a Model Context Protocol (MCP) server that exposes Google's Veo2 video generation capabilities. It allows clients to generate videos from text prompts or images, and access the generated videos through MCP resources.

<a href="https://glama.ai/mcp/servers/@mario-andreschak/mcp-veo2">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@mario-andreschak/mcp-veo2/badge" alt="Video Generation with Veo2 MCP server" />
</a>

## Features

- Generate **videos from text** prompts
- Generate **videos from images**
- Access generated videos through MCP resources
- Example video generation templates
- Support for both stdio and SSE transports

## Example Images
![1dec9c71-07dc-4a6e-9e17-8da355d72ba1](https://github.com/user-attachments/assets/ba987d14-dd46-49ac-9b31-1ce398e86c6f)


## Example Image to Video
[Image to Video - from Grok generated puppy](https://github.com/mario-andreschak/mcp-veo2/raw/refs/heads/main/example-files/2a6a0807-d323-4424-a48a-e40a82b883bb.mp4)

[Image to Video - from real cat](https://github.com/mario-andreschak/mcp-veo2/raw/refs/heads/main/example-files/55b9f28b-61a6-423e-bb86-f3791c639177.mp4)


## Prerequisites

- Node.js 18 or higher
- Google API key with access to Gemini API and Veo2 model (= You need to set up a credit card with your API key! -> Go to aistudio.google.com )

## Installation

### Quick Start with npx (Recommended)

The easiest way to use this package is with npx:

```bash
# Set your Google API key
export GOOGLE_GENAI_API_KEY="your-api-key-here"

# Run with stdio transport (for MCP clients)
npx @raihan0824/mcp-veo2

# Run with SSE transport (for web interfaces)
npx @raihan0824/mcp-veo2 sse

# Get help
npx @raihan0824/mcp-veo2 --help
```

### Installing in [FLUJO](https://github.com/mario-andreschak/FLUJO/)
1. Click Add Server
2. Copy & Paste Github URL into FLUJO
3. Click Parse, Clone, Install, Build and Save.

### Installing via Smithery

To install mcp-video-generation-veo2 for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@mario-andreschak/mcp-veo2):

```bash
npx -y @smithery/cli install @mario-andreschak/mcp-veo2 --client claude
```

### Manual Installation
1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/mcp-video-generation-veo2.git
   cd mcp-video-generation-veo2
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Create a `.env` file with your Google API key:
   ```bash
   cp .env.example .env
   # Edit .env and add your Google API key
   ```

   The `.env` file supports the following variables:
   - `GOOGLE_API_KEY`: Your Google API key (required)
   - `PORT`: Server port (default: 3000)
   - `STORAGE_DIR`: Directory for storing generated videos (default: ./generated-videos)
   - `LOG_LEVEL`: Logging level (default: fatal)
     - Available levels: verbose, debug, info, warn, error, fatal, none
     - For development, set to `debug` or `info` for more detailed logs
     - For production, keep as `fatal` to minimize console output

   **S3 Cloud Storage (Optional):**
   - `USE_S3`: Enable S3 storage (default: false)
   - `S3_ENDPOINT`: S3 endpoint URL (e.g., `https://s3.amazonaws.com` or custom endpoint)
   - `S3_REGION`: S3 region
   - `S3_BUCKET`: S3 bucket name
   - `S3_ACCESS_KEY`: S3 access key
   - `S3_SECRET_KEY`: S3 secret key

   When S3 is enabled (`USE_S3=true`), generated videos will be uploaded to your S3 bucket and served via public URLs. This is recommended for production deployments as it provides better scalability and reduces local storage requirements.

4. Build the project:
   ```bash
   npm run build
   ```

## Usage

### Starting the Server

#### With npx (Recommended)

```bash
# Set your API key
export GOOGLE_GENAI_API_KEY="your-api-key-here"

# stdio Transport (Default) - for MCP clients
npx @raihan0824/mcp-veo2

# SSE Transport - for web interfaces  
npx @raihan0824/mcp-veo2 sse
```

#### After Manual Installation

You can start the server with either stdio or SSE transport:

##### stdio Transport (Default)

```bash
npm start
# or
npm start stdio
```

##### SSE Transport

```bash
npm start sse
```

This will start the server on port 3000 (or the port specified in your `.env` file).

## Storage Configuration

This MCP server supports two storage modes for generated videos:

### Local Storage (Default)

By default, videos are stored locally in the `STORAGE_DIR` directory. This is suitable for development and small-scale deployments.

```bash
# Local storage configuration
USE_S3=false
STORAGE_DIR=./storage
```

### S3 Cloud Storage

For production deployments, you can configure S3-compatible storage to store videos and images in the cloud. This provides better scalability, reliability, and reduces local storage requirements.

```bash
# S3 storage configuration
USE_S3=true
S3_ENDPOINT=https://parahu.box.cloudeka.id
S3_REGION=parahu
S3_BUCKET=ai-cloudeka
S3_ACCESS_KEY=your_s3_access_key
S3_SECRET_KEY=your_s3_secret_key
```

**Benefits of S3 Storage:**
- **Scalability**: No local disk space limitations
- **Reliability**: Built-in redundancy and backup
- **Performance**: CDN-like distribution
- **Cost-effective**: Pay only for what you use
- **Accessibility**: Generated content accessible via public URLs

**Supported S3 Providers:**
- Amazon S3
- DigitalOcean Spaces
- Cloudeka Object Storage
- MinIO
- Any S3-compatible storage service

### MCP Tools

The server exposes the following MCP tools:

#### generateVideoFromText

Generates a video from a text prompt.

Parameters:
- `prompt` (string): The text prompt for video generation
- `config` (object, optional): Configuration options
  - `aspectRatio` (string, optional): "16:9" or "9:16"
  - `personGeneration` (string, optional): "dont_allow" or "allow_adult"
  - `numberOfVideos` (number, optional): 1 or 2
  - `durationSeconds` (number, optional): Between 5 and 8
  - `enhancePrompt` (boolean, optional): Whether to enhance the prompt
  - `negativePrompt` (string, optional): Text describing what not to generate

Example:
```json
{
  "prompt": "Panning wide shot of a serene forest with sunlight filtering through the trees, cinematic quality",
  "config": {
    "aspectRatio": "16:9",
    "personGeneration": "dont_allow",
    "durationSeconds": 8
  }
}
```

#### generateVideoFromImage

Generates a video from an image.

Parameters:
- `image` (string): Base64-encoded image data
- `prompt` (string, optional): Text prompt to guide the video generation
- `config` (object, optional): Configuration options (same as above, but personGeneration only supports "dont_allow")

#### generateImage

Generates an image from a text prompt using Google Imagen.

Parameters:
- `prompt` (string): The text prompt for image generation
- `numberOfImages` (number, optional): Number of images to generate (default: 1)
- `includeFullData` (boolean, optional): Whether to include the full image data in response (default: true)

Example:
```json
{
  "prompt": "A beautiful sunset over mountains with clouds, photorealistic style",
  "numberOfImages": 1,
  "includeFullData": true
}
```

#### listGeneratedVideos

Lists all generated videos.

#### listGeneratedImages

Lists all generated images.

### MCP Resources

The server exposes the following MCP resources:

#### videos://{id}

Access a generated video by its ID.

#### videos://templates

Access example video generation templates.

#### images://{id}

Access a generated image by its ID.

#### images://templates

Access example image generation templates.

## Development

### Project Structure

- `src/`: Source code
  - `index.ts`: Main entry point
  - `server.ts`: MCP server configuration
  - `config.ts`: Configuration handling
  - `tools/`: MCP tool implementations
  - `resources/`: MCP resource implementations
  - `services/`: External service integrations
  - `utils/`: Utility functions

### Building

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

## License

MIT