gemini-image-mcp
Drives the gemini.google.com consumer web UI to generate images from text prompts, saving the full-resolution results to disk and returning the file paths along with Gemini's reply text and chat URL. Supports continuing the remembered conversation for iterative edits (e.g. "same character, night scene") or starting a fresh chat, plus a status tool to check whether the signed-in Google session is still valid.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gemini-image-mcp generate an image of a cozy cabin in a snowy forest at dusk"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
gemini-image-mcp
MCP server that drives gemini.google.com in headless Chrome to generate images, saves them to disk and returns the paths. Supports continuing the same conversation (for iterative edits) or starting a new one.
It signs in with your own Google account through a normal browser session, so it needs no API key -- and equally, it gives no API guarantees. Read the Caveats before relying on it.
Requirements
Node.js 18+
Google Chrome installed (the real browser -- Chromium builds are not used)
A Google account with access to Gemini
A desktop session you can open a browser window in, for the one-time sign-in (a headless server with no display cannot complete it locally)
Linux and macOS should work -- Chrome is located automatically in the usual places, and
GEMINI_MCP_CHROME overrides the path -- but it has only been exercised on Windows.
Related MCP server: nano-banana-mcp
How the Google session is connected
There is no API key and no password handling. The server uses a dedicated
persistent Chrome profile at ~/.gemini-image-mcp/profile:
npm run loginopens your real Chrome (not bundled Chromium) with that profile, visible.You sign in to Google by hand in that window — 2FA, passkey, whatever your account uses.
Close the window. Chrome has written the cookies into the profile directory.
The server then launches the same profile in Chrome's headless mode, so it is already signed in. Nothing in this code ever sees or stores a credential.
Chrome is spawned directly with --remote-debugging-port and attached via
connectOverCDP, rather than through Playwright's launchPersistentContext.
Playwright drives Chrome over --remote-debugging-pipe, which Chrome 154 refuses
for this profile (it exits immediately with code 21); the port transport works.
The session lasts as long as Google keeps it alive (typically weeks/months). When it
expires, every tool returns NOT_SIGNED_IN — re-run npm run login.
Using a separate profile (rather than your everyday Chrome profile) matters: Chrome locks a profile directory while it is running, so automation against your main profile would fail whenever Chrome is open.
Setup
git clone https://github.com/sedvis/gemini-image-mcp.git
cd gemini-image-mcp
npm install
npm run login # opens Chrome; sign in by hand, onceCheck it worked, then try a generation straight from the CLI:
node src/smoke.mjs status
node src/smoke.mjs gen "a red fox in a misty forest at sunrise" newRegistering with an MCP client
Any MCP client that speaks stdio works. The server is node <abs-path>/src/server.mjs:
{
"mcpServers": {
"gemini-image": {
"command": "node",
"args": ["/abs/path/to/gemini-image-mcp/src/server.mjs"]
}
}
}For Claude Code specifically: if you open this repo as your project, the bundled
.mcp.json is picked up automatically -- it resolves its own path:
"args": ["${CLAUDE_PROJECT_DIR:-.}/src/server.mjs"]CLAUDE_PROJECT_DIR is set in the spawned server's environment rather than Claude
Code's own, so the :-. default is what makes the expansion work from .mcp.json;
a bare relative path is not reliably resolved against the project root.
To use it from other projects, register it once globally with an absolute path:
claude mcp add gemini-image --scope user -- node /abs/path/to/gemini-image-mcp/src/server.mjsTools
Tool | Purpose |
|
|
| Forget the remembered thread, open a fresh chat |
| Is the profile still signed in? |
conversation: "continue" reuses the remembered chat URL, which is persisted to
~/.gemini-image-mcp/state.json — so follow-ups like "same character, night scene"
keep working across server restarts.
Env vars
Var | Default | Meaning |
|
| Set to |
|
| Profile + state location |
|
| Default save directory |
| auto-detected | Full path to the Chrome executable, if it is not in a standard location |
Troubleshooting
Symptom | Cause / fix |
| Session expired, or an interstitial is blocking. Re-run |
| Profile locked by another Chrome using the same |
Image returned but | Both capture paths failed. See How images are saved below. |
File is a | The download button was missed, so the downscaled preview was read off the DOM instead. Re-run; check the |
Wrong/duplicate image returned | Only the newest |
How images are saved
Images are saved via Gemini's own "Download full-sized image" button, which yields the real asset -- a ~2816x1536 JPEG at 300 DPI.
This matters: the <img> rendered in the page is only a downscaled ~1024px preview, so
reading pixels off the DOM element silently loses most of the resolution. That read is
kept purely as a fallback, and files it produces are marked -preview- in the filename.
The fallback also cannot use fetch: image URLs are CORS-blocked from the page context,
and a fresh turn serves the image as a blob: URL, so it goes through a canvas read.
Caveats
This drives the consumer web UI, so it depends on Gemini's DOM. If Google reshuffles the markup, generation returns a
warningplus a debug screenshot instead of files; the selectors live in oneSELobject at the top ofsrc/gemini.mjs.Automating a consumer web account is outside Gemini's intended use; for anything production-facing, the Gemini API with an API key is the supported route.
Google may occasionally show an interstitial (consent, "verify it's you") that headless cannot clear. Run with
GEMINI_MCP_HEADLESS=0once to clear it by hand.The profile directory holds a live Google session. Treat it like a credential: it is kept outside the repo (in
~/.gemini-image-mcp/) so it is never committed, and it is per-machine -- do not copy it between machines or users.Rate limits, model choice and output size are whatever your Google account's Gemini gives you; this server does not control them.
License
MIT -- see LICENSE.
Available Tools
3 toolsgemini_generate_imageGenerate an image with GeminiA
Sends a prompt to gemini.google.com in a headless Chrome signed in with the local Google profile, waits for the generated image(s), saves them to disk and returns the file paths. conversation="continue" keeps the existing chat thread (so you can iterate: "make it darker"); conversation="new" starts a fresh chat.
Inputs: prompt (required), save_dir, conversation, timeout_seconds.
gemini_new_conversationStart a new Gemini conversationA
Drops the remembered chat thread and opens a fresh one.
Inputs: no named parameters.
gemini_session_statusCheck the Gemini browser sessionA
Reports whether the local Chrome profile still has a valid Google/Gemini session. If signedIn is false, the user must run "npm run login" in the gemini-image-mcp project and sign in by hand (profile: /root/.gemini-image-mcp/profile).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool targets a distinct action: resetting the chat thread, checking session status, and generating images. There is mild overlap since gemini_new_conversation and gemini_generate_image's conversation="new" both start a fresh chat, but descriptions make the distinction clear.
All three tools follow a consistent gemini_<verb>_<noun> snake_case pattern (new_conversation, session_status, generate_image). No deviations in style or casing.
Three tools is slightly lean for the surface, but the server's scope is narrow (image generation via a browser session) and each tool earns its place. No obvious padding or missing operations-driven bloat.
The core lifecycle—verify session, start/continue a conversation, generate and save images—is covered. Login is handled externally via npm run login, so the only minor gap is no tooling around listing or managing previously saved images.
Maintenance
Related MCP Connectors
Generate and edit realistic images from a prompt. Returns the image and a download link.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Generate images, videos, voiceovers, and captions from a chat prompt.
Create images and videos from prompts, with options for image mixing, reference images, and start/…
Related MCP Servers
- FlicenseAqualityDmaintenanceGenerates images from text prompts using ElevenLabs' image generation API via browser automation, with support for multiple models and persistent authentication.3-
- FlicenseNot gradedqualityDmaintenanceGenerates images using Google's Gemini model, with options to save to file or return as base64 data URL.-
- AlicenseAqualityDmaintenanceEnables image generation and transformation using Gemini API, returning file paths instead of base64 data to avoid token limit issues in Claude Code.21MIT
- FlicenseNot gradedqualityDmaintenanceEnables image generation and editing via third-party relay services. Returns local file paths and Markdown display hints.-