Gemini Image MCP

An MCP server for generating and editing images with Google's Gemini image models (Nano Banana, Nano Banana 2, Nano Banana Pro). It exposes one tool, generate_image, which AI tools like Claude, Codex, and Cline can call using your own API key.

What it does

• generate_image handles text-to-image, plus editing and composition when you pass it reference images (local file paths or base64).

• Every generation knob is exposed per call: temperature (1), topP (0.95), topK, maxOutputTokens (65536 for flash/lite, 32768 for pro), seed, stopSequences, presencePenalty, frequencyPenalty, systemInstruction, thinkingLevel (minimal/high), thinkingBudget, enableGoogleSearch (default true), imageSize (512/1K/2K/4K), aspectRatio ("auto" default + standard ratios), personGeneration.

• Ships an instructions block and per-parameter descriptions, so MCP clients figure out how to use the tool without extra prompting.

• Saves images to disk and returns file paths. No base64 in the response, so a 4K image won't eat the client's context window.

• Errors come back with hints (bad key, rate limit, safety block, unknown model) instead of a raw API dump.

• stdio transport, the usual setup for local MCP servers.

Requirements

• Bun 1.0+

• A Gemini API key from https://aistudio.google.com/apikey

Install

bun install

Configuration

Three environment variables, normally set in the MCP client's config:

Models you can pick:

Models can also be specified with the models/ prefix (e.g. models/gemini-3.1-flash-image).

Client setup

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Cline (VS Code)

cline_mcp_settings.json:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/gemini-image-mcp/index.ts"],
      "env": {
        "GEMINI_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Codex

~/.codex/config.toml:

[mcp_servers.gemini-image]
command = "bun"
args = ["run", "/absolute/path/to/gemini-image-mcp/index.ts"]
env = { GEMINI_API_KEY = "YOUR_KEY_HERE" }

From npm (bunx/npx)

Once the package is published, point your client at bunx instead:

{
  "mcpServers": {
    "gemini-image": {
      "command": "bunx",
      "args": ["gemini-image-mcp"],
      "env": { "GEMINI_API_KEY": "YOUR_KEY_HERE" }
    }
  }
}

generate_image parameters

Only prompt is required. Everything else defaults to something sensible for image generation.

The tool returns a text summary with the saved file path(s), the model, the effective config, and token usage. It never returns image data inline; open the file to see the result.

Things you can ask your AI

• "Generate a 16:9 hero image of a rainy Tokyo street at night, cinematic neon lighting."

• "Edit /tmp/product.png: put it on a marble table with soft morning light" (this uses referenceImages).

• "Generate a 4K poster with the exact headline 'LAUNCH DAY' using gemini-3-pro-image."

Development

bun test              # unit tests (config, schema, request/response parsing)
bun run typecheck     # tsc --noEmit
bun run inspector     # interactive MCP inspector (needs GEMINI_API_KEY)
bun run start         # run the server on stdio

Troubleshooting

• "Missing Gemini API key": put GEMINI_API_KEY in the env block of the client's MCP config. Setting it in your shell isn't enough for GUI apps like Claude Desktop, since they don't read your shell environment.

• Safety blocks: rephrase the prompt. If people are involved, check personGeneration.

• 429 / quota exceeded: wait and retry, or stick to gemini-3.1-flash-image, which has the higher quota.

• Logs: the server writes logs to stderr only. stdout carries the MCP protocol, so don't add console.log anywhere.

Author

Thomi Jasir dev@venobi.com

License

MIT