Earlybird-Technology/mcp-gemini-image

mcp-gemini-image

An MCP (Model Context Protocol) server that provides image generation capabilities using Google's Gemini 2.5 Flash Image Preview model.

Features

• Text-to-Image Generation: Generate images from text prompts
• Image-to-Image Generation: Transform existing images with text guidance
• Resource Management: Access generated images through MCP resources
• Automatic Cleanup: Auto-deletes images older than 8 hours on startup
• Security: Built-in rate limiting, input validation, and file size limits

Installation

Prerequisites

You'll need a Google Gemini API key. Get one from Google AI Studio.

Option 1: Install with Claude Code (Recommended)

1. Clone or download this repository to your local machine

2. Add the MCP server using the Claude CLI:

macOS/Linux:

claude mcp add mcp-gemini-image --env GEMINI_API_KEY=your-api-key-here \
  -- node /absolute/path/to/mcp-gemini-image/index.js

Windows:

claude mcp add mcp-gemini-image --env GEMINI_API_KEY=your-api-key-here -- cmd /c node C:\absolute\path\to\mcp-gemini-image\index.js

3. Restart Claude Code to load the server

Note: The -- separator is required to separate Claude CLI flags from the server command.

Option 2: Manual Configuration

Add this configuration to your Claude Desktop config file:

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

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

Option 3: Install with Gemini Code Assist

1. Clone or download this repository to your local machine

2. Open your Gemini settings file:

   • VS Code: ~/.gemini/settings.json
   • IntelliJ: Create mcp.json in your IDE's configuration directory

3. Add the server configuration:

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

4. Restart your IDE to load the MCP server

Option 4: Install with OpenAI Codex

1. Clone or download this repository to your local machine

2. Open your Codex config file: ~/.codex/config.toml

3. Add the server configuration:

[mcp_servers.mcp-gemini-image]
command = "node"
args = ["/absolute/path/to/mcp-gemini-image/index.js"]
env = { "GEMINI_API_KEY" = "your-api-key-here" }

4. Restart Codex to load the MCP server

Option 5: Install from NPM (if published)

npm install -g mcp-gemini-image

Then configure in your MCP client:

{
  "mcpServers": {
    "mcp-gemini-image": {
      "command": "mcp-gemini-image",
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage

Once configured, the server provides two tools:

generate_image

Generate an image from a text prompt.

Parameters:

• prompt (string, required): Text description of the image to generate
• input_image (string, optional): Base64-encoded input image for image-to-image generation
• input_image_mime_type (string, optional): MIME type of input image (default: "image/png")

Example:

{
  "prompt": "A serene mountain landscape at sunset",
  "input_image": "base64encodeddata...",
  "input_image_mime_type": "image/jpeg"
}

cleanup_images

Delete generated images based on age.

Parameters:

• max_age_hours (number, optional): Delete only images older than this many hours. If not specified, deletes all images.

Example:

{
  "max_age_hours": 24
}

Resources

Generated images are exposed as MCP resources with URIs in the format:

gemini-image:///<filename>

These resources can be read by MCP clients to access the generated images.

Security Features

• Rate Limiting: 10 requests per minute
• Input Validation: Validates prompts and base64 data
• File Size Limits:
  • Generated images: 10MB max
  • Input images: 20MB max (base64)
  • Prompts: 10,000 characters max
• Path Traversal Protection: Validates all file paths
• Extension Whitelist: Only allows png, jpeg, jpg, webp, gif
• Automatic Cleanup: Removes images older than 8 hours on startup

Development

Run the server directly:

npm start

The server uses stdio transport and is designed to be invoked by MCP clients.

File Structure

.
├── index.js           # Main server implementation
├── package.json       # NPM configuration
├── .gitignore        # Excludes generated_images/
├── CLAUDE.md         # Claude Code guidance
└── generated_images/ # Auto-generated images (created automatically)

Troubleshooting

"GEMINI_API_KEY environment variable is required"

Make sure you've set the GEMINI_API_KEY environment variable in your MCP client configuration.

"Rate limit exceeded"

The server limits requests to 10 per minute. Wait a moment before trying again.

"Invalid or unsupported image type"

Only png, jpeg, jpg, webp, and gif formats are supported.

License

MIT