Google Gemini Image Generation MCP Server

A Model Context Protocol (MCP) server that provides image generation capabilities using Google's Gemini API (including Nano Banana models and Imagen) for Claude Code and other MCP clients.

Features

• Text-to-image generation with Google Gemini's image generation models
• Support for multiple models:
  • Gemini Flash: Fast and efficient (gemini-2.5-flash-image)
  • Gemini Pro: High quality with 4K support (gemini-3-pro-image-preview)
  • Imagen 4.0: Google's dedicated image generation model
• Multiple resolutions (1K, 2K, 4K)
• Multiple aspect ratios (1:1, 16:9, 4:3, 21:9, etc.)
• Easy integration with Claude Code Skills

Prerequisites

• Node.js 18 or higher
• A Google Gemini API key (get one from Google AI Studio)

Installation

Install via npm:

npm install -g @ckz_2055/gemini-image-mcp

Or use directly with npx (no installation required):

npx @ckz_2055/gemini-image-mcp

Get your API key:

1. Visit Google AI Studio
2. Sign in with your Google account
3. Click "Create API Key"
4. Copy your API key (starts with AIzaSy)

Configuration for Claude Code

Option 1: Using Claude Desktop

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": {
      "command": "npx",
      "args": ["-y", "@ckz_2055/gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Replace your-api-key-here with your actual Google Gemini API key.

Option 2: Using Claude Code CLI

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "gemini-image": {
      "command": "npx",
      "args": ["-y", "@ckz_2055/gemini-image-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Replace your-api-key-here with your actual Google Gemini API key.

Usage

Once configured, the MCP server provides the following tool:

generate_image

Generate images from text descriptions using Google Gemini.

Parameters:

• prompt (required): Text description of the image to generate. Be descriptive - describe the scene, don't just list keywords.
• model (optional): Model to use:
  • "gemini-flash" (default): Fast and efficient
  • "gemini-pro": High quality, supports 4K resolution
  • "imagen": Google's Imagen 4.0 model
• resolution (optional): "1K" (default), "2K", or "4K" (4K only with gemini-pro/imagen)
• aspect_ratio (optional): "1:1" (default), "16:9", "4:3", "21:9", etc.
• num_images (optional): Number of images (1-4, only supported by Imagen model)

Example usage in Claude Code:

User: Generate an image of a sunset over mountains
Claude: [Uses generate_image tool with prompt="A beautiful sunset over mountains with orange and pink sky"]

Example with specific parameters:

User: Create a wide 4K landscape image
Claude: [Uses generate_image with model="gemini-pro", resolution="4K", aspect_ratio="16:9"]

Using with Skills

Skills can now use the MCP tool for image generation. Here's an example skill:

Create .claude/skills/blog-publisher/SKILL.md:

---
name: Blog Publisher
description: Convert markdown articles to HTML with AI-generated images
tags: [markdown, html, images, blog]
---

# Blog Publisher Skill

This skill converts markdown articles into styled HTML pages with AI-generated images.

## How it works

When the user provides a markdown file:
1. Parse the markdown content
2. Identify places where images would enhance the content
3. Use the `generate_image` MCP tool to create relevant images
4. Convert markdown to HTML with syntax highlighting
5. Insert generated images as base64 data URIs
6. Apply beautiful CSS styling

## Usage

User: Convert my article to HTML with images Assistant: [Uses this skill to process the markdown and generate images]

## Example Implementation

The skill will call the generate_image tool like this:

```typescript
// The MCP tool is called automatically by Claude
generate_image({
  prompt: "A futuristic cityscape at sunset with flying cars",
  model: "gemini-flash",
  aspect_ratio: "16:9"
})

## Response Format

Images are returned as base64 data URIs that can be used directly in HTML:

```html
<img src="data:image/png;base64,iVBORw0KG..." alt="Generated image">

Testing

Test the MCP server directly:

# Build and run
npm run build
npm start

Or use development mode (auto-rebuild):

npm run dev

Models & Capabilities

| Model | ID | Resolution | Features | |-------|-----|-----------|----------| | Gemini Flash | gemini-2.5-flash-image | 1K, 2K | Fast, efficient | | Gemini Pro | gemini-3-pro-image-preview | 1K, 2K, 4K | High quality, multi-turn editing | | Imagen 4.0 | imagen-4.0-generate-001 | 1K, 2K | Professional, batch generation |

Troubleshooting

"GEMINI_API_KEY environment variable is required"

Make sure your API key is set in:

• Your .env file, OR
• The Claude config file under env.GEMINI_API_KEY

"Gemini API error: 401"

Your API key is invalid or not authorized. Verify your key at Google AI Studio.

"Gemini API error: 429"

You've hit the rate limit. Wait a moment and try again, or check your quota in Google AI Studio.

"Module not found" errors

Run npm install and npm run build to ensure dependencies are installed and TypeScript is compiled.

"No images were generated"

The API may have rejected your prompt. Try rephrasing it to be more descriptive and specific.

Development

• npm run build - Build TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm start - Run the MCP server

API Documentation

For more details on the Google Gemini API:

• Gemini Image Generation (Nano Banana)
• Imagen API
• Google AI Studio

Example: Creating a Markdown to HTML Converter Skill

Once this MCP server is installed, you can create a skill that uses it:

---
name: Article to HTML
description: Convert markdown articles to beautiful HTML with generated images
---

# Article to HTML Converter

Converts markdown articles to styled HTML pages with AI-generated hero images and diagrams.

## Usage

User: "Convert article.md to HTML"

The skill will:
1. Read the markdown file
2. Generate a hero image based on the article title
3. Generate diagrams for code examples
4. Convert to HTML with syntax highlighting
5. Apply CSS styling
6. Save as HTML file

All image generation is handled by the gemini-image MCP server!

License

MIT

Support

For issues with:

• This MCP server: Open an issue in this repository
• Google Gemini API: Visit Google AI Studio
• Claude Code: Visit code.claude.com