Skip to main content
Glama
collactivelabs

Gemini Image & Video Generation MCP

by collactivelabs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Gemini Image & Video Generation MCP

A production-ready Model Context Protocol (MCP) server that enables Claude and other LLMs to generate images and videos using Google's Gemini AI models (Gemini 2.0 Flash and Veo 2.0).

🌟 Features

Core Capabilities

  • ✨ Image Generation - Create images using Gemini 2.0 Flash (gemini-2.0-flash-preview-image-generation)

  • 🎬 Video Generation - Generate videos using Veo 2.0 (veo-2.0-generate-001)

  • 🎨 Image-to-Video - Animate images into videos with Veo 2.0

  • 💾 Local Storage - Automatically save generated content

  • ⚙️ Parameter Control - Fine-tune temperature, topK, and topP

Production Features

  • 🔒 Optional Authentication - Token-based API security

  • ⚡ Response Caching - 30-minute TTL cache for repeated prompts

  • 📊 Rate Limiting - Prevent API abuse (100/15min general, 20/15min generation)

  • ✅ Input Validation - Comprehensive request validation

  • 📄 Pagination - Efficient gallery browsing with sorting

  • 🔐 Configurable CORS - Environment-based origin control

  • 📚 OpenAPI Documentation - Interactive Swagger UI at /api-docs

  • 🧪 Test Suite - 17 automated tests with Jest

  • 🐳 Docker Support - Easy containerized deployment

Related MCP server: imagine-mcp

📋 Prerequisites

  • Node.js 18 or higher

  • Google API Key with access to:

    • Gemini 2.0 Flash (image generation)

    • Veo 2.0 (video generation)

  • Docker (optional, for containerized deployment)

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/your-org/gemini-image-gen-mcp.git
cd gemini-image-gen-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

Running the Server

Option 1: Node.js (Development)

# MCP server only (for Claude integration)
npm start

# Web server with REST API + UI
npm run web

# Or use the start script
./start-server.sh --both      # Both servers
./start-server.sh --mcp-only  # MCP only
./start-server.sh --web-only  # Web only

Option 2: Docker (Production)

docker-compose up -d

The web interface will be available at http://localhost:3070

🎯 API Endpoints

Generation Endpoints

  • POST /api/generate-image - Generate an image from a text prompt

  • POST /api/generate-video - Generate a video from a text prompt

  • POST /api/generate-video-from-image - Generate a video from an initial image

Gallery Endpoints

  • GET /api/images?page=1&limit=20 - List generated images (paginated)

  • GET /api/videos?page=1&limit=20 - List generated videos (paginated)

System Endpoints

  • GET /health - Health check

  • GET /api-docs - Interactive Swagger UI documentation

  • GET /api-docs.json - OpenAPI JSON specification

  • GET /api/cache/stats - View cache statistics

  • POST /api/cache/clear - Clear response cache (requires auth)

📖 API Documentation

Interactive API documentation is available at:

The Swagger UI provides:

  • Complete endpoint documentation

  • Request/response schemas

  • Try-it-now functionality

  • Authentication testing

  • Parameter descriptions and examples

🔐 Authentication

Authentication is optional and can be enabled by setting the API_AUTH_TOKEN environment variable:

# In .env file
API_AUTH_TOKEN=your-secure-token-here

Using Authentication

Bearer Token (Recommended):

curl -H "Authorization: Bearer your-secure-token-here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset over mountains"}' \
  http://localhost:3070/api/generate-image

Query Parameter (Alternative):

curl -X POST \
  "http://localhost:3070/api/generate-image?token=your-secure-token-here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset over mountains"}'

⚙️ Configuration Options

All configuration is done via environment variables in .env:

Variable

Description

Default

GEMINI_API_KEY

Required - Google Gemini API key

-

API_AUTH_TOKEN

Optional - API authentication token

-

MCP_AUTH_TOKEN

Optional - MCP server authentication

-

PORT

Web server port

3070

OUTPUT_DIR

Base directory for generated files

./generated-images

LOG_LEVEL

Logging level (debug, info, warn, error)

info

CORS_ORIGINS

Comma-separated allowed origins

*

RATE_LIMIT_MAX

Max requests per 15min per IP

100

GENERATION_RATE_LIMIT

Max generation requests per 15min

20

ENABLE_CACHE

Enable response caching

true

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Current Test Coverage:

  • 2 test suites

  • 17 tests passing

  • Coverage: Authentication, Tool Schemas, Input Validation

🐳 Docker Deployment

Using Docker Compose (Recommended)

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Manual Docker Build

# Build image
docker build -t gemini-image-gen-mcp .

# Run container
docker run -d \
  -p 3070:3070 \
  -e GEMINI_API_KEY=your_key_here \
  -v $(pwd)/generated-images:/app/generated-images \
  -v $(pwd)/generated-videos:/app/generated-videos \
  gemini-image-gen-mcp

🔌 Usage with Claude

Claude Desktop Configuration

Add to your Claude Desktop config file:

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

{
  "mcpServers": {
    "gemini-image-generation": {
      "command": "node",
      "args": ["/full/path/to/gemini-image-gen-mcp/src/mcp-server.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Claude API Usage

# Example prompt to Claude
"Please generate an image of a serene mountain landscape at sunset using the Gemini image generation tool"

Claude will automatically invoke the MCP server's generate_image tool.

🎨 Web Interface

The web interface provides three main sections:

1. Generator Tab

  • Enter text prompts for image/video generation

  • Adjust generation parameters (temperature, topP, topK)

  • Use sample prompts for quick testing

  • View generation results with enhanced prompts

2. Gallery Tab

  • Browse all generated images and videos

  • Pagination support (20 items per page)

  • Sorted by newest first

  • Click to view full size

3. About Tab

  • Project information

  • Feature list

  • Configuration details

  • API documentation links

📊 Performance & Optimization

Response Caching

  • Automatically caches successful generation results

  • 30-minute TTL (configurable)

  • Reduces API costs for repeated prompts

  • Cache key includes: prompt + model + parameters

  • View cache stats at /api/cache/stats

Exponential Backoff

  • Smart video polling (2s → 30s max)

  • Reduces API calls by ~60%

  • Prevents API rate limiting

Async I/O

  • Non-blocking file operations

  • Improved server responsiveness

  • Better handling of concurrent requests

Pagination

  • Constant memory usage

  • Handles galleries with thousands of items

  • Sorted by modification time

🛡️ Security Features

  • ✅ Input Validation - All parameters validated with express-validator

  • ✅ Rate Limiting - Two-tier system (general + generation specific)

  • ✅ Request Size Limits - 10MB max to prevent DoS

  • ✅ CORS Configuration - Environment-based origin control

  • ✅ Optional Authentication - Token-based API security

  • ✅ No Hardcoded Secrets - All credentials via environment variables

🔧 Troubleshooting

Common Issues

"GEMINI_API_KEY is not set" error:

# Make sure .env file exists and contains:
GEMINI_API_KEY=your_actual_key_here

Port already in use:

# Change port in .env file:
PORT=3080

Cache not working:

# Check cache is enabled in .env:
ENABLE_CACHE=true
# View cache stats:
curl http://localhost:3070/api/cache/stats

Rate limit exceeded:

# Increase limits in .env:
RATE_LIMIT_MAX=200
GENERATION_RATE_LIMIT=50

📝 Example API Requests

Generate an Image

curl -X POST http://localhost:3070/api/generate-image \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic cityscape at night with neon lights",
    "temperature": 0.8,
    "topP": 0.95,
    "topK": 40
  }'

Generate a Video

curl -X POST http://localhost:3070/api/generate-video \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A bird flying through a forest",
    "temperature": 1.0
  }'

List Images with Pagination

curl "http://localhost:3070/api/images?page=1&limit=10"

🤝 Contributing

Contributions are welcome! Please:

  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. Open a Pull Request

Development Guidelines

  • Run tests before committing: npm test

  • Follow existing code style

  • Update documentation for new features

  • Add tests for new functionality

📄 License

ISC

🙏 Acknowledgments

📞 Support

For issues and questions:

  • Open an issue on GitHub

  • Check the API Documentation

  • Review the troubleshooting section above

Made with ❤️ for the AI community

Available Tools

3 tools
generate_imageB

Generate an image using Google Gemini

ParametersJSON Schema
NameRequiredDescriptionDefault
saveNoWhether to save the generated image to the filesystem
topKNoTop-k parameter for sampling
topPNoTop-p parameter for sampling
modelNoModel to usegemini-2.0-flash-preview-image-generation
promptYesText description of the image to generate
temperatureNoTemperature for generation (0.0 to 1.0)

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the action and model, omitting any context about side effects such as saving to filesystem, return format, or permission requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no unnecessary words. It efficiently states the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema and no annotations, the description does not explain the return value, output format, or any operational details. It relies entirely on the schema, which is insufficient for a generation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the parameters are already fully documented in the schema. The description adds no additional meaning about parameter usage or format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'generate' with the resource 'an image' and names the underlying model 'Google Gemini'. It clearly distinguishes from sibling tools generate_video and generate_video_from_image, which target video.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus the video generation siblings. The name and verb imply image generation, but there is no mention of alternatives or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_videoC

Generate a video using Google Gemini Veo 2.0

ParametersJSON Schema
NameRequiredDescriptionDefault
saveNoWhether to save the generated video to the filesystem
topKNoTop-k parameter for sampling
topPNoTop-p parameter for sampling
modelNoModel to useveo-2.0-generate-001
promptYesText description of the video to generate
temperatureNoTemperature for generation (0.0 to 1.0)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic action without mentioning side effects, output format, execution time, or save behavior, which is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no redundancy. It front-loads the purpose clearly and contains no unnecessary text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite full schema coverage, the tool has no annotations and no output schema. The description does not explain return values, usage context, or differentiation from siblings. For a generative tool that may save files, more contextual information is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters are well documented in the schema. The description itself adds no parameter details, but the baseline of 3 is appropriate since the schema handles the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a video using Google Gemini Veo 2.0, providing a specific verb and resource. It does not explicitly differentiate from sibling tools like generate_video_from_image, but the mention of the model implies a direct text-to-video generation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or how it differs from generate_video_from_image.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_video_from_imageC

Generate a video from an initial image using Google Gemini Veo 2.0

ParametersJSON Schema
NameRequiredDescriptionDefault
saveNoWhether to save the generated video to the filesystem
topKNoTop-k parameter for sampling
topPNoTop-p parameter for sampling
modelNoModel to useveo-2.0-generate-001
promptYesText description of the video to generate
temperatureNoTemperature for generation (0.0 to 1.0)

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must bear the full burden of behavioral disclosure, but it only states the core action. It does not disclose what happens to the generated video (e.g., whether it is saved to the filesystem), the output format, or any required authentication or rate limits. The description also does not mention the 'save' parameter's default behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that gets to the point quickly. It is structurally efficient and easy to parse, although it may be too terse for a tool with 6 parameters and no output schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is severely incomplete for a tool with 6 parameters and no output schema. It lacks critical information: how the initial image is supplied, what the return value or output looks like, when to adjust sampling parameters, and any side effects. The absence of an image parameter in the schema further compounds this incompleteness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although the schema covers 100% of parameters with descriptions, the tool description introduces an 'initial image' concept that is not present in the schema, creating confusion. It also does not explain the sampling parameters (topK, topP, temperature) or how they affect results, leaving the agent to rely solely on the schema without additional context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (generate a video) and the resource (from an initial image using Gemini Veo 2.0), which distinguishes it from siblings like generate_image and generate_video. However, the phrase 'from an initial image' is not reflected in the input schema, which has no image parameter, making the purpose slightly ambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool vs. alternatives, and does not explain how to provide the 'initial image' (since no image parameter exists in the schema). It fails to mention prerequisites, exclusions, or any context for choosing this tool over generate_video.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedgenerate_image
    • First observedgenerate_video
    • First observedgenerate_video_from_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct media type and input condition: image, video, and video-from-image. No overlap or ambiguity between the three.

Naming Consistency5/5

All tools follow a clear generate_<target> pattern, with the third adding a descriptive suffix 'from_image' that still fits the convention. Consistent and predictable.

Tool Count4/5

Three tools is on the lower end but appropriate for a focused media generation server covering the core generation capabilities. Not excessively thin.

Completeness4/5

The server covers primary generation workflows (image, video, video from image). Minor gaps like image editing or video variations exist but are not essential for the stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers