Server data from the Official MCP Registry
Google Gemini image generation, editing, and local processing via MCP
Google Gemini image generation, editing, and local processing via MCP
Valid MCP server (2 strong, 3 medium validity signals). 3 known CVEs in dependencies (0 critical, 3 high severity) Package registry verified. Imported from the Official MCP Registry.
5 files analyzed · 4 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: GEMINI_API_KEY
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-jimothysnicket-gemini-image": {
"env": {
"GEMINI_API_KEY": "your-gemini-api-key-here"
},
"args": [
"-y",
"@jimothy-snicket/gemini-image-mcp"
],
"command": "npx"
}
}
}From the project's GitHub README.
MCP server for Google Gemini image generation, editing, and processing. Two tools, no bloat.
Built on Gemini's native image generation API (generateContent), not the deprecated Imagen API. If you're migrating from Imagen (shutting down June 2026), this is what you move to — multi-turn editing, reference images, and all the features Imagen didn't have.
npm install -g @jimothy-snicket/gemini-image-mcp
Or use directly with npx:
npx -y @jimothy-snicket/gemini-image-mcp
Claude Code (one command):
claude mcp add gemini-image -- npx -y @jimothy-snicket/gemini-image-mcp
Requires a GEMINI_API_KEY environment variable — see Setup for details.
Set up a config file (optional):
npx @jimothy-snicket/gemini-image-mcp --init
Creates ~/.gemini-image-mcp.json with commented defaults. For project-specific overrides:
npx @jimothy-snicket/gemini-image-mcp --init --local
generations.jsonl logs every generation with prompt, params, costGo to Google AI Studio and create an API key. It's free to start with generous rate limits.
The server reads your key from the GEMINI_API_KEY environment variable. Set it once so it's available in every session:
Windows (PowerShell — run as admin):
[System.Environment]::SetEnvironmentVariable('GEMINI_API_KEY', 'your-key-here', 'User')
Then restart your terminal.
macOS / Linux:
echo 'export GEMINI_API_KEY="your-key-here"' >> ~/.bashrc
source ~/.bashrc
(Use ~/.zshrc if you're on zsh.)
Verify it's set:
echo $GEMINI_API_KEY
Pick the method that matches how you use MCP:
claude mcp add gemini-image -- npx -y @jimothy-snicket/gemini-image-mcp
Claude Code will pick up GEMINI_API_KEY from your environment automatically.
.mcp.json)Add to .mcp.json in your project root or ~/.claude/.mcp.json for global access:
{
"mcpServers": {
"gemini-image": {
"command": "npx",
"args": ["-y", "@jimothy-snicket/gemini-image-mcp"],
"env": {
"GEMINI_API_KEY": "${GEMINI_API_KEY}"
}
}
}
}
The ${GEMINI_API_KEY} syntax reads the value from your shell environment — your actual key never gets written into config files.
Edit claude_desktop_config.json:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json{
"mcpServers": {
"gemini-image": {
"command": "npx",
"args": ["-y", "@jimothy-snicket/gemini-image-mcp"],
"env": {
"GEMINI_API_KEY": "${GEMINI_API_KEY}"
}
}
}
}
Restart Claude Desktop after saving.
Any client that supports stdio transport works. Point it at npx -y @jimothy-snicket/gemini-image-mcp and pass GEMINI_API_KEY in the environment.
${GEMINI_API_KEY} syntax in config files references your environment — the key itself stays in your shell profile..mcp.json is in a project repo, add it to .gitignore or use the global config at ~/.claude/.mcp.json instead.All optional. The only required setup is GEMINI_API_KEY (covered above).
| Variable | Default | Description |
|---|---|---|
OUTPUT_DIR | ~/gemini-images | Default directory for saved images |
DEFAULT_MODEL | gemini-2.5-flash-image | Default Gemini model |
LOG_LEVEL | info | debug, info, or error |
REQUEST_TIMEOUT_MS | 60000 | API request timeout in milliseconds |
MAX_REQUESTS_PER_HOUR | 0 (unlimited) | Max image generations per rolling hour |
MAX_COST_PER_HOUR | 0 (unlimited) | Max estimated cost (USD) per rolling hour |
SESSION_TIMEOUT_MS | 1800000 (30min) | Multi-turn session expiry |
Set these the same way as GEMINI_API_KEY, or pass them in the env block of your MCP config.
Rate limiting is recommended when agents have access to this tool. An agent in a loop can generate images quickly — set MAX_REQUESTS_PER_HOUR=20 and MAX_COST_PER_HOUR=5 as sensible defaults.
Instead of environment variables, you can use a JSON config file. Create one with:
npx @jimothy-snicket/gemini-image-mcp --init
This creates ~/.gemini-image-mcp.json with all defaults and inline documentation. Edit it to set your preferences.
Priority: env vars > local config (.gemini-image-mcp.json in CWD) > global config (~/.gemini-image-mcp.json) > defaults.
You can also set per-tool defaults so every request uses your preferred settings:
{
"defaultModel": "gemini-3.1-flash-image-preview",
"defaults": {
"generate": {
"aspectRatio": "16:9",
"resolution": "2K"
},
"process": {
"removeBackground": { "color": "#00FF00" },
"trim": true
}
}
}
Per-request parameters always override config defaults.
generate_image| Parameter | Required | Description |
|---|---|---|
prompt | Yes | Text description or editing instruction |
images | No | Array of file paths to input/reference images |
model | No | Gemini model ID |
aspectRatio | No | 1:1, 16:9, 9:16, 3:2, 2:3, 4:3, 3:4, 21:9 |
resolution | No | 1K, 2K, 4K |
outputDir | No | Override output directory for this request |
filename | No | Base name for saved file (e.g. hero-banner). Auto-versioned if duplicate. |
subfolder | No | Subfolder within output directory (e.g. landing-page) |
sessionId | No | Continue a multi-turn editing session from a previous response |
seed | No | Integer seed for reproducible generation |
useSearchGrounding | No | Enable Google Search grounding (gemini-3.1-flash) |
{
"imagePath": "/home/user/gemini-images/hero-banner.png",
"mimeType": "image/png",
"model": "gemini-2.5-flash-image",
"sessionId": "session-1711929600000-a1b2c3",
"sessionTurn": 1,
"usage": {
"promptTokens": 5,
"outputTokens": 1295,
"imageTokens": 1290,
"thinkingTokens": 412,
"totalTokens": 1712,
"estimatedCost": "$0.0390"
},
"session": {
"generationsThisSession": 3,
"totalCostThisSession": "$0.1161",
"generationsThisHour": 5,
"limit": {
"maxPerHour": 20,
"maxCostPerHour": 5,
"remainingThisHour": 15
}
}
}
Text-to-image:
"Generate a hero image for a SaaS landing page, modern gradient style, 16:9"
Image editing:
"Take this screenshot and redesign the header with a dark theme" (with image paths)
Multi-turn refinement:
"Draw a logo for a coffee shop" → get result with
sessionId→ "Make it more minimal" (passsessionIdback)
Organized output:
"Generate a hero banner" with
filename: "hero",subfolder: "landing-page"→ saves to~/gemini-images/landing-page/hero.png
High quality:
"A photorealistic product shot of headphones on marble, 4K" (using gemini-3-pro-image-preview)
process_imageLocal image processing via sharp. Free, fast, no API calls.
| Parameter | Required | Description |
|---|---|---|
imagePath | Yes | Path to the image file to process |
crop | No | Crop by pixel dimensions, aspect ratio, or focal point strategy |
resize | No | Resize to width/height (maintains aspect ratio) |
removeBackground | No | Remove background by threshold (white) or chroma key (any solid colour) |
trim | No | Auto-remove whitespace/transparent borders |
format | No | Convert to png, jpeg, or webp |
quality | No | Output quality for JPEG/WebP (1-100) |
filename | No | Base name for saved file. Auto-versioned if duplicate. |
subfolder | No | Subfolder within output directory |
outputDir | No | Override output directory |
// Pixel-exact
{"width": 500, "height": 300, "left": 100, "top": 50}
// Aspect ratio (center crop)
{"aspectRatio": "16:9"}
// Focal point — shifts crop to the most interesting region
{"aspectRatio": "16:9", "strategy": "attention"}
// Detail-based — shifts crop to the most detailed region
{"aspectRatio": "16:9", "strategy": "entropy"}
// White/light background (threshold)
{"threshold": 240}
// Green screen (chroma key)
{"color": "#00FF00"}
// Any solid colour
{"color": "#0000FF", "tolerance": 60}
Chroma key uses HSV colour space keying with smoothstep feathering, spill suppression (removes colour fringe on edge pixels), and 5-pass edge anti-aliasing. Default tolerance is 80. Always use #00FF00 for AI-generated green screens — it works better than matching the exact shade Gemini produces.
Note: Chroma key works best with high-contrast subjects (red, blue, black on green). For yellow, green, or glass/reflective subjects, use the canvas approach instead — feed a solid colour background image to generate_image and let Gemini place the subject with correct lighting.
Subject on a specific background (canvas approach):
generate_image → "Place a [subject] on this background" with images: [solid colour canvas]
One API call. Best for yellow, green, or glass subjects where chroma key struggles.
Transparent asset from green screen:
generate_image → "A product photo on a bright green background"
process_image → removeBackground {color: "#00FF00"} + trim
Two tool calls, zero cost for the processing step. Best for high-contrast subjects.
Favicon from a generated logo:
process_image → removeBackground {threshold: 230} + trim + resize {width: 192, height: 192}
Social card from a photo:
process_image → crop {aspectRatio: "16:9", strategy: "attention"} + resize {width: 1200}
WebP conversion for web:
process_image → format: "webp" + quality: 85
| Model | Strengths | Resolution | Notes |
|---|---|---|---|
gemini-2.5-flash-image | Fast, cheap (~$0.04/image) | 1K only | Default. Deprecates Oct 2026 |
gemini-3-pro-image-preview | Best quality, text rendering | 1K, 2K, 4K | Up to 14 reference images |
gemini-3.1-flash-image-preview | Speed + quality balance | 512, 1K, 2K, 4K | Google Search grounding |
bun install
bun run build # TypeScript -> dist/
bun run dev # Run directly with Bun
MIT
Be the first to review this server!
by Modelcontextprotocol · AI & ML
Dynamic and reflective problem-solving through structured thought sequences
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
by mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.