MCP Image Gen
A Model Context Protocol (MCP) server for generating images using Google's Gemini AI models.
Features
- 🎨 Generate high-quality images from text prompts using Gemini AI
- 📐 Customizable aspect ratios (1:1, 16:9, 9:16, 4:3, 3:4)
- 🔧 Configurable image sizes (small to 4K resolution)
- ⚙️ Flexible configuration via JSON file
- 💾 Automatic local image saving with organized filenames (saves to ~/gemini_images by default)
- 🚀 Built on the MCP SDK for seamless integration
⚠️ Known Issues
- Aspect ratio and image size parameters may not be working correctly - Images are currently being generated in landscape format regardless of the specified aspect ratio. This is being investigated. The API calls appear correct, but the Gemini API may not be respecting the configuration parameters as expected.
Models Supported
- gemini-3-pro-image-preview (Default): Professional-grade, supports up to 4K resolution
- gemini-2.5-flash-image: Optimized for speed, generates 1024px resolution
Installation
- Clone the repository:
git clone https://github.com/Legorobotdude/mcp-image-gen.git
cd mcp-image-gen
- Install dependencies:
pnpm install
- Build the project:
pnpm build
Configuration
Environment Variables
Set your Gemini API key:
export GEMINI_API_KEY=your_api_key_here
Get your API key from Google AI Studio.
Config File (Optional)
Create a config.json file in the project root to customize defaults:
{
"model": "gemini-3-pro-image-preview",
"defaultAspectRatio": "1:1",
"defaultImageSize": "large",
"outputDirectory": "~/gemini_images"
}
Available Options:
model:"gemini-3-pro-image-preview"or"gemini-2.5-flash-image"defaultAspectRatio:"1:1","16:9","9:16","4:3", or"3:4"defaultImageSize:"small"(1K - 1024px)"medium"(2K - 2048px)"large"(2K - 2048px)"xlarge"(4K - 4096px - only for gemini-3-pro-image-preview)
outputDirectory: Path where generated images will be saved (default:~/gemini_images, can use absolute paths or~for home directory)
Usage with 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": {
"mcp-image-gen": {
"command": "node",
"args": ["/absolute/path/to/mcp-image-gen/dist/index.js"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}
Tool: generate_image
Generate an image from a text prompt.
Parameters
- prompt (required): Text description of the image to generate
- aspectRatio (optional): Aspect ratio -
"1:1","2:3","3:2","3:4","4:3","4:5","5:4","9:16","16:9","21:9" - imageSize (optional): Resolution -
"small"(1K),"medium"(2K),"large"(2K),"xlarge"(4K) - negativePrompt (optional): Describe what you DON'T want in the image
Example Usage in Claude
Generate an image of a serene mountain landscape at sunset with vibrant colors
Create a 16:9 image of a futuristic city skyline at night in xlarge size
Generate a portrait of a wise old wizard with a long beard, aspect ratio 3:4, medium size
Response Format
The tool returns a JSON response with:
{
"success": true,
"imagePath": "/Users/yourusername/gemini_images/1234567890_serene_mountain_landscape.png",
"prompt": "serene mountain landscape at sunset",
"model": "gemini-3-pro-image-preview",
"aspectRatio": "1:1",
"imageSize": "large",
"message": "Image generated successfully and saved to: /Users/yourusername/gemini_images/1234567890_serene_mountain_landscape.png"
}
Image Quality Notes
- All generated images include a SynthID watermark (Google's digital watermark)
- gemini-3-pro-image-preview: Best for high-quality, detailed images up to 4K
- gemini-2.5-flash-image: Best for quick generation, fixed at 1024px resolution
Development
Watch mode for development:
pnpm dev
Build for production:
pnpm build
Troubleshooting
"GEMINI_API_KEY environment variable is required"
Make sure you've set the GEMINI_API_KEY environment variable or added it to your MCP configuration.
Images not generating
- Check your API key is valid
- Verify you have internet connectivity
- Ensure the output directory is writable
Size options not working
The gemini-2.5-flash-image model only supports 1024px resolution regardless of the size parameter. Use gemini-3-pro-image-preview for higher resolutions.
License
MIT