gemini-imagen-mcp-server by serkanhaslak - MCP Server

Gemini Imagen MCP Server for Claude Code

🎨 Perfect Claude Code MCP server for AI-powered image generation with Google's Gemini Imagen API. Generate images directly in your project's imagen/ folder while coding!

✨ Why This MCP Server?

🔥 Claude Code Optimized: Designed specifically for Claude Code workflow
📁 Project Integration: Images saved directly in your project's imagen/ folder
🎯 Zero Setup: Just add API key and start generating images
⚡ Multiple Models: Support for Imagen 3, Imagen 4, and Imagen 4 Ultra
📦 Batch Processing: Generate multiple images efficiently
🎛️ Advanced Controls: Aspect ratios, negative prompts, seeds, and more

🚀 Quick Start

1. Get Your API Key

Get a free Gemini API key from Google AI Studio

2. Install & Configure

Zero Installation Required - Use with npx:

Add to your Claude Code MCP settings:

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

3. Start Generating Images!

Generate an image of "a futuristic robot coding in a modern office"

Images will be saved to imagen/ folder in your current project! 🎯

📁 How It Works

When you generate images, they're automatically saved with descriptive filenames:

your-project/
├── imagen/
│   ├── imagen-4-ultra_2024-01-15T10-30-45_futuristic_robot_coding_1.png
│   ├── imagen-4_2024-01-15T10-32-12_sunset_landscape_1.png
│   └── imagen-3_2024-01-15T10-35-01_abstract_art_design_1.png
├── src/
└── README.md

🎨 Available Models

Model	Quality	Speed	Best For
imagen-4-ultra	🌟🌟🌟🌟🌟	⚡⚡⚡	Premium quality, detailed images
imagen-4	🌟🌟🌟🌟	⚡⚡⚡⚡	Great quality, faster generation
imagen-3	🌟🌟🌟	⚡⚡⚡⚡⚡	Good quality, fastest generation

💡 Usage Examples

Basic Image Generation

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

Advanced Parameters

Generate an image with these settings:
- Prompt: "minimalist website mockup for a coffee shop"
- Model: imagen-4-ultra
- Aspect ratio: 16:9
- Negative prompt: "cluttered, busy, complex"

Batch Generation

Generate images for these prompts:
1. "logo design for a tech startup"
2. "mobile app interface wireframe"
3. "modern dashboard UI design"

Design Assets for Projects

Create a collection of images:
- "app icon design, minimalist, blue and white"
- "hero banner for landing page, technology theme"
- "user avatar placeholder, professional style"

🎛️ Advanced Features

Aspect Ratios

1:1 - Perfect squares (logos, avatars)
16:9 - Widescreen (banners, headers)
9:16 - Portrait (mobile screens)
4:3 - Standard (presentations)
3:4 - Portrait (posters)

Control Parameters

Negative Prompts: Specify what to avoid
Seeds: Get reproducible results
Person Generation: Control person appearance
Output Format: JPEG or PNG

Batch Processing

Generate multiple images efficiently with shared settings:

Generate a batch of logo variations with these prompts:
["minimalist coffee logo", "geometric coffee logo", "vintage coffee logo"]
using imagen-4-ultra with 1:1 aspect ratio

⚙️ Configuration Options

Command Line Arguments

# Use different default model
npx gemini-imagen-mcp-server --model imagen-4-ultra

# Enable batch processing
npx gemini-imagen-mcp-server --batch --max-batch-size 8

# Custom output directory
npx gemini-imagen-mcp-server --output-dir assets/images

Available Options

Option	Description	Default
`--model`	Default model (imagen-3, imagen-4, imagen-4-ultra)	imagen-4-ultra
`--batch`	Enable batch processing	disabled
`--max-batch-size`	Max batch size (1-8)	4
`--output-dir`	Output directory	imagen

🛠️ Installation Methods

Option 1: NPX (Recommended)

No installation needed! Just configure and use:

{
  "mcpServers": {
    "gemini-imagen": {
      "command": "npx",
      "args": ["-y", "gemini-imagen-mcp-server"],
      "env": {"GEMINI_API_KEY": "your-key"}
    }
  }
}

Option 2: Global Install

npm install -g gemini-imagen-mcp-server

Then configure:

{
  "mcpServers": {
    "gemini-imagen": {
      "command": "gemini-imagen-claude-code",
      "env": {"GEMINI_API_KEY": "your-key"}
    }
  }
}

Option 3: Local Development

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

🧪 Development & Testing

Build & Test

# Build the project
npm run build

# Run comprehensive tests
npm run test

# Development with auto-rebuild
npm run watch

# Interactive testing with MCP Inspector
npm run dev

Project Structure

src/
├── index.ts          # Main MCP server implementation
build/                # Compiled JavaScript
test_server.js        # Comprehensive test suite
tsconfig.json         # TypeScript configuration

🔧 Available Tools

`generate_image`

Generate single or multiple images with full parameter control.

`batch_generate`

Process multiple prompts efficiently with shared settings.

`list_models`

Show all available Imagen models and their capabilities.

`health_check`

Check server status, API connectivity, and configuration.

📚 Resources

`generation_history`

Access recent image generation history with full parameters.

`api_documentation`

Comprehensive API documentation with examples.

🐛 Troubleshooting

Common Issues

"GEMINI_API_KEY not found"

Ensure API key is set in MCP configuration
Verify the key is valid and has billing enabled

"No images generated"

Check if prompt violates content policies
Try a simpler prompt first
Verify API quota hasn't been exceeded

"Permission denied"

Ensure Claude Code has write access to project directory
Check that imagen/ folder can be created

Debug Mode

Run with debug logging:

DEBUG=* npx gemini-imagen-mcp-server

🎯 Perfect for Claude Code Projects

This MCP server is specifically designed for developers using Claude Code:

Project-Centric: Images go directly in your project
Developer-Friendly: Descriptive filenames with timestamps
Workflow Integration: Generate assets while coding
Version Control Ready: Images in dedicated folder
Batch Operations: Generate multiple assets efficiently

🔒 Security & Best Practices

✅ API keys handled securely through environment variables
✅ Input validation with Zod schemas
✅ Comprehensive error handling
✅ Rate limiting and quota management
✅ No sensitive data logged or stored

📈 Use Cases

Web Development

Hero images and banners
UI/UX mockups and wireframes
Logo and branding assets
Placeholder images

App Development

App icons and splash screens
User interface elements
Marketing assets
Documentation images

Content Creation

Blog post illustrations
Social media graphics
Presentation visuals
Product mockups

🤝 Contributing

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Make changes and add tests
Run tests: npm test
Commit: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
Open Pull Request

📊 API Limits & Pricing

Free Tier: Generous monthly quota
Rate Limits: Automatically handled
Batch Processing: Optimized for efficiency
Cost Control: Monitor usage with health checks

📜 License

MIT License - see file for details.

🌟 Why Choose This MCP Server?

🎯 Purpose-Built: Specifically for Claude Code workflows
⚡ Zero Config: Works out of the box with just API key
📁 Smart Organization: Images organized in project folders
🔄 Active Development: Regular updates and improvements
📖 Great Documentation: Comprehensive guides and examples
🛠️ Developer-Friendly: Built by developers, for developers

Ready to supercharge your Claude Code projects with AI-generated images?

Install now and start creating! 🚀

# Just add to your MCP config and go!
npx -y gemini-imagen-mcp-server --help