Gemini Imagen MCP Server

A production-ready Model Context Protocol (MCP) server that integrates Google's Gemini Imagen API with Claude Desktop for AI-powered image generation. Features multiple model support, batch processing, and advanced generation parameters.

🚀 Quick Start

1. Get a Gemini API key from Google AI Studio
2. Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

   {
     "mcpServers": {
       "gemini-imagen": {
         "command": "npx",
         "args": ["-y", "gemini-imagen-mcp-server", "--model", "imagen-4-ultra", "--batch"],
         "env": {"GEMINI_API_KEY": "your-api-key-here"}
       }
     }
   }

3. Restart Claude Desktop and start generating images!

No installation required - npx handles everything automatically!

✨ Features

• 🎨 Multiple Imagen Models: Support for Imagen 3, Imagen 4, and Imagen 4 Ultra
• 📦 Batch Processing: Generate multiple images efficiently with configurable batch sizes
• 🎛️ Advanced Parameters: Negative prompts, person generation controls, custom seeds
• 📐 Flexible Aspect Ratios: Support for 1:1, 3:4, 4:3, 9:16, 16:9
• 🔧 CLI Configuration: Command-line arguments for model selection and batch settings
• 🛡️ Production Ready: Comprehensive error handling, validation, and logging
• 📊 Generation History: Track and review previous generations with full parameters
• 🏥 Health Monitoring: Built-in health checks and API connectivity diagnostics
• 📚 Built-in Documentation: Comprehensive API documentation and examples

🚀 Quick Start

Prerequisites

• Node.js 18+
• Google Gemini API key from Google AI Studio
• Claude Desktop or MCP-compatible client

Installation

🚀 Option 1: Zero Installation with npx (Recommended)

No installation needed! Just configure Claude Desktop:

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

{
  "mcpServers": {
    "gemini-imagen": {
      "command": "npx",
      "args": [
        "-y",
        "gemini-imagen-mcp-server",
        "--model", "imagen-4-ultra",
        "--batch",
        "--max-batch-size", "4"
      ],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

That's it! Claude Desktop will automatically download and run the server when needed.

Note: The first time you use it, npx will download the package (takes a few seconds). Subsequent uses will be instant.

📦 Option 2: Global NPM Installation

Install globally:

npm install -g gemini-imagen-mcp-server

Configure Claude Desktop:

{
  "mcpServers": {
    "gemini-imagen": {
      "command": "gemini-imagen-mcp",
      "args": ["--model", "imagen-4-ultra", "--batch", "--max-batch-size", "4"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

📁 Option 3: Manual Installation

1. Clone and setup:

git clone https://github.com/serkanhaslak/gemini-imagen-mcp-server.git
cd gemini-imagen-mcp-server
npm install

2. Build the server:

npm run build

3. Configure Claude Desktop:

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "gemini-imagen": {
      "command": "node",
      "args": ["/absolute/path/to/gemini-imagen-mcp-server/build/index.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Restart Claude Desktop and start generating images!

Updates

npx users (Option 1): No action needed! npx automatically uses the latest version.

Global NPM users (Option 2):

npm update -g gemini-imagen-mcp-server

Manual installation users (Option 3):

git pull
npm install
npm run build

🎛️ Command Line Options

Configure the server behavior with command line arguments:

# Use different model as default
node build/index.js --model imagen-4-ultra

# Enable batch processing with custom batch size
node build/index.js --batch --max-batch-size 8

# Custom output directory
node build/index.js --output-dir /path/to/your/images

# Combine multiple options
node build/index.js --model imagen-4 --batch --max-batch-size 4 --output-dir ./my-images

Available Options

🖼️ Smart Image Display Modes

The server automatically detects your environment and displays images appropriately:

Display Modes

• auto (default): Automatically detects environment
  • Claude Desktop: Shows images inline in chat
  • CLI/Project: Saves images to files + shows small images inline
• inline: Always shows images inline in chat (best for Claude Desktop)
• files: Always saves images to files (best for CLI/scripting)
• hybrid: Saves files AND shows small images inline

Environment Detection

The server detects your environment based on:

• Claude Desktop: Process environment variables and parent process
• Project/CLI: Working directory, presence of package.json or .git folder

This ensures images display perfectly whether you're using Claude Desktop or working in a development environment!

🔧 Available Tools

generate_image

Generate single or multiple images with comprehensive parameters.

Parameters:

• prompt (required): Text description of the image
• model: Model selection (imagen-3, imagen-4, imagen-4-ultra)
• number_of_images: Number of images to generate (1-4)
• aspect_ratio: Image aspect ratio (1:1, 3:4, 4:3, 9:16, 16:9)
• person_generation: Control person generation (dont_allow, allow_adult, allow_all)
• negative_prompt: What to avoid in the image
• seed: Random seed for reproducible results
• output_format: Output format (image/jpeg, image/png)

Example:

Generate an image of "a serene mountain landscape at sunset" using imagen-4-ultra with 16:9 aspect ratio

batch_generate

Process multiple prompts efficiently with shared settings.

Parameters:

• prompts: Array of text prompts
• model: Model to use for all images
• shared_settings: Common settings (aspect_ratio, person_generation, output_format)

Example:

Generate images for these prompts: ["peaceful forest", "bustling city", "calm ocean"] using imagen-4 with 3:4 aspect ratio

list_models

Show available Imagen models and their capabilities.

health_check

Check server status, API connectivity, and configuration.

📚 Available Resources

generation_history

Access recent image generation history with full parameters and metadata.

api_documentation

Comprehensive API documentation with examples and best practices.

📖 Usage Examples

Basic Generation

Generate an image of "a cat wearing a space helmet"

Advanced Generation

Generate an image with these parameters:
- Prompt: "futuristic city with flying cars"
- Model: imagen-4-ultra
- Aspect ratio: 16:9
- Negative prompt: "dark, gloomy, crowded"
- Seed: 12345

Batch Processing

Generate images for these prompts:
1. "sunrise over mountains"
2. "cozy coffee shop interior"
3. "abstract digital art"

🧪 Development

Building and Testing

# Build the project
npm run build

# Run tests
npm run test

# Development with auto-rebuild
npm run watch

# Test with MCP Inspector
npm run inspector

Testing with MCP Inspector

The MCP Inspector provides an interactive interface for testing:

npm run dev

This opens a web interface where you can test all tools and resources interactively.

🏗️ Architecture

The server implements the MCP protocol with:

• 4 Tools: generate_image, batch_generate, list_models, health_check
• 2 Resources: generation_history, api_documentation
• Multiple Models: Imagen 3, Imagen 4, Imagen 4 Ultra
• Batch Processing: Configurable parallel processing
• Error Handling: Comprehensive error handling and validation
• Type Safety: Full TypeScript implementation with Zod validation

📊 Model Comparison

🔒 Security & Best Practices

• API Key Security: Never commit API keys to version control
• Environment Variables: Use environment variables for sensitive data
• Input Validation: All inputs are validated using Zod schemas
• Error Handling: Comprehensive error handling prevents crashes
• Rate Limiting: Respects API rate limits and handles gracefully

🐛 Troubleshooting

Common Issues

Server won't start:

• Check that GEMINI_API_KEY is set correctly
• Verify Node.js version (18+)
• Ensure dependencies are installed: npm install

API authentication errors:

• Verify API key is correct and has proper permissions
• Check that billing is enabled for your Google Cloud project
• Ensure the API key hasn't expired

Generation fails:

• Check prompt doesn't violate content policies
• Verify model availability in your region
• Check API quotas and limits

Claude Desktop integration:

• Ensure configuration file path is correct
• Verify server path is absolute
• Restart Claude Desktop after configuration changes

Debug Mode

Enable debug logging:

DEBUG=* node build/index.js

📋 API Reference

Environment Variables

CLI Arguments

All CLI arguments are optional and have sensible defaults.

Error Codes

• INVALID_API_KEY: API key is missing or invalid
• RATE_LIMIT_EXCEEDED: API rate limit reached
• CONTENT_POLICY_VIOLATION: Prompt violates content policies
• INVALID_PARAMETERS: Invalid tool parameters
• NETWORK_ERROR: Network connectivity issues

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run tests: npm run test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

📜 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol for the specification
• Google Gemini API for the Imagen models
• Anthropic for Claude Desktop integration

🔗 Links

• Google Gemini API Documentation
• Model Context Protocol
• Claude Desktop
• MCP Servers Repository

Ready to generate amazing images with Claude? Install the server and start creating! 🎨