gemini-image-mcp
Summary: This server lets you generate and edit images for free through your own Gemini web account by wrapping the Gemini web app, with a small toolset for generation, editing, and model discovery.
Generate images —
generate_imagecreates one or more new images from a text prompt and returns the saved file paths plus the path to a cumulative HTML gallery for browsing results.Edit images —
edit_imageapplies a text instruction to existing local image files (e.g. a photo or a previously generated image) and saves/returns the edited results.List models —
list_modelsshows which Gemini image/chat models your signed-in account can use, so you can pass one as themodelargument to override the default.Choose a model — both generation tools accept an optional
modelparameter; otherwise the server's configured default or the account's default is used.No API key required — it drives the consumer Gemini web app with your session cookies instead of the paid, metered Gemini API (unofficial and against Google's ToS; region/age-gated and fragile).
Beyond the exposed schema (per the README): background jobs and batches, exact sizes/aspect ratios, text-spelling checks, previews, optional GitHub publishing, and a directly importable MCP-free
corelibrary.
Allows generating and editing images using the Gemini web app (gemini.google.com) with your own browser session cookies, providing tools for image generation, editing, and model listing without using the paid API.
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 fox in a snowy forest"
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
An MCP server that generates and edits images by driving the consumer Gemini web app
(gemini.google.com) with your own browser session cookies, via the
gemini-webapi library — instead of the paid,
metered Gemini API.
Why this exists: the official Gemini API bills per image. If you already have a Gemini web account where image generation works, this lets you use that account instead of a metered API key. The trade-off is described below — read it before using this.
This project is not affiliated with, endorsed by, or supported by Google. "Gemini" is
a Google product; this is an independent, unofficial client built on top of the
third-party gemini-webapi library.
Disclaimer
Driving the consumer web app with your own session cookies, instead of an official API key, is outside Google's Terms of Service for that product. Any consequence — rate limiting, a challenge, or account action — lands on your Google account, not on this code. This tool doesn't take a position on whether that trade-off is worth it beyond making sure you know it up front. See the License section for the full no-warranty disclaimer.
Related MCP server: nano-banana-mcpv2
Features
generate_imageandedit_imageMCP tools backed by your own Gemini web session — no API key, no per-image billing.list_modelsto discover which models your account can use.Exact sizes for marketplace cards (e.g. Uzum 1080×1440), projects and tags in the gallery, previews returned to the model, and a rendered-text spelling check.
Background jobs and batches with idempotency keys, rate-limit backoff, retries and resume after a crash, so slow generations never time out silently.
Every generated or edited image accumulates into a single, self-contained, interactive HTML gallery (
output/gallery.html) — the primary way to browse your output. Click any image for a detail view with its full prompt, metadata, and copy buttons.Optional GitHub publishing: point it at a repository you own and every new image is also uploaded there, giving you a stable public URL to use in other projects. Off unless you configure it — see Publishing images to GitHub.
gemini_image_mcp.corehas zeromcpimports, so it can be imported directly by other Python code (e.g. a Telegram bot) without going through the MCP protocol at all.Automatic image-format correction: Gemini doesn't always return the format you'd expect, so saved files are renamed to match their actual content (e.g.
.jpginstead of a mislabeled.png).
Requirements
Python >= 3.11
A Gemini web account where image generation already works manually in your browser. Image generation is 18+ and region-limited, and requires Gemini Apps Activity to be turned on for your account. If the web UI itself won't generate an image, this tool can't either — fix that first.
Install / Quickstart
uv synccopy .env.example .envEdit .env and paste in GEMINI_1PSID / GEMINI_1PSIDTS (see
Getting your cookies below), then run the smoke test:
uv run python scripts/smoke_test.py "a watercolor fox"The smoke test prints the saved image path(s) and the gallery path on success, or a clean error message (e.g. about missing/expired cookies) on failure.
Getting your cookies
In Chrome, sign in and go to
https://gemini.google.com. Manually generate an image there first (e.g. ask it to "generate an image of a fox") and confirm it actually works. If the web UI itself won't generate an image, this tool cannot either — fix that first.Press
F12to open Chrome DevTools.Go to the Application tab -> Storage -> Cookies ->
https://gemini.google.com.Find the cookie named
__Secure-1PSID. Click it and copy its Value column (a long string). This is yourGEMINI_1PSID.Find the cookie named
__Secure-1PSIDTS. Copy its Value the same way. This is yourGEMINI_1PSIDTS.Copy
.env.exampleto.envand paste the two values intoGEMINI_1PSIDandGEMINI_1PSIDTS.
Automatic cookies from your browser (recommended)
Instead of pasting cookies, sign in to https://gemini.google.com in a supported browser
and leave GEMINI_1PSID / GEMINI_1PSIDTS empty. The server reads both cookies straight
from the browser's cookie store (via browser-cookie3) at startup, and again whenever
Gemini reports the session as signed out - so a fresh login is picked up without touching
.env. The browser doesn't need to be running. Stay signed in there (no private window,
don't clear its cookies).
In auto mode the server tries Firefox, LibreWolf, Edge, Chrome, Brave, Chromium, Vivaldi
and Opera in that order, and uses the first one whose Gemini login works. On macOS only
Firefox and LibreWolf are tried automatically, because reading Chromium-based browsers
there triggers a Keychain password prompt. Name the browser explicitly to use it anyway.
Browser | Windows | macOS | Linux |
Firefox, LibreWolf | Yes | Yes | Yes |
Edge, Brave, Vivaldi, Opera, Chromium | Yes | Yes (Keychain prompt) | Yes |
Chrome | No - see below | Yes (Keychain prompt) | Yes |
Safari | - | Yes (with Full Disk Access) | - |
GEMINI_COOKIE_SOURCE-auto(default:.envvalues if set, else the browsers above, also used as a fallback when the.envvalues are stale),env(only.env), or one browser:firefox,librewolf,edge,chrome,brave,chromium,vivaldi,opera,safari.GEMINI_BROWSER_COOKIE_FILE- path to a specific profile's cookie database, if you have several profiles (forauto, it applies to Firefox).GEMINI_FIREFOX_COOKIE_FILEstill works as the older name.
Run uv run gemini-image-mcp doctor --offline to see which browser was found, or why
none could be read.
Cookie lifetime
__Secure-1PSIDTS rotates frequently. gemini-webapi refreshes it in the background
while the server is running and persists the refreshed value to the path in
GEMINI_COOKIE_PATH (default: a private per-user folder: %LOCALAPPDATA%\gemini-image-mcp\cookies on Windows,
~/Library/Application Support/gemini-image-mcp/cookies on macOS,
~/.local/state/gemini-image-mcp/cookies on Linux), so in the happy path you only paste
cookies once. The cache is kept outside output/ on purpose, so sharing or publishing
your images never exposes your session. If you paste cookies by hand
and find yourself re-pasting often, keeping Firefox or Edge signed in to Gemini and
letting the server read them is a more durable workaround.
Chrome on Windows can't be read automatically. Since Chrome 127, Chrome on Windows encrypts its cookies with app-bound encryption, which can only be decrypted with administrator rights, and an MCP server should never run as administrator. If Chrome is your main browser, sign in to Gemini once in Firefox or Edge just for this server, or copy the two values by hand as above.
These cookies are your account
__Secure-1PSID and __Secure-1PSIDTS are equivalent to being logged in as you. Never
commit them, paste them into a chat, or share them with anyone. .env is gitignored by
default — keep it that way.
Registering with Claude Code
claude mcp add gemini-image-mcp -- uv run --directory "/path/to/gemini-image-generator-mcp" gemini-image-mcp(On Windows this might look like
uv run --directory "C:\Users\you\projects\gemini-image-generator-mcp" gemini-image-mcp.)
This registers the server to run via the gemini-image-mcp console script that uv sync
installs into the project's virtual environment (defined in pyproject.toml's
[project.scripts]), always executed from the correct project directory regardless of
your current working directory.
Equivalent JSON (e.g. for claude_desktop_config.json or .mcp.json):
{
"mcpServers": {
"gemini-image-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/gemini-image-generator-mcp",
"gemini-image-mcp"
]
}
}
}Tools
Tool | Arguments | Returns |
|
| Path(s) of the new image(s), gallery path, model used, public URL if published, text-check result, and JPEG previews when |
|
| Same as |
| same as above ( | Returns a job id immediately; the work runs in the background. |
|
| Job status ( |
|
| Recent jobs from any server process. |
|
| Starts a background batch: rate-limit backoff (1/2/4 min, then pause), retries, optional regeneration on misspelled text, per-item status, progress saved after every item. |
|
| Batch progress and per-item paths / errors / text-check flags. |
|
| Continues a paused, interrupted or partly failed batch; finished items are skipped. |
|
| Stops a batch after its current item. |
|
| JPEG previews so the model can QA images (spelling, layout). |
|
| Reads the rendered text back via Gemini and flags missing or misspelled words (Uzbek |
|
| Uploads existing images to your configured GitHub repo and returns their public URLs. |
| (none) | Models available to the signed-in account. Fails with a clear error after ~55 s instead of hanging. |
| (none) | Instant, no-network health check (version, sign-in state, running jobs, limits). Call before long work. |
|
| Setup health check; |
Sizes and aspect ratios
aspect_ratio ("3:4", "16:9", ...) is written into the prompt, and the result is then
center-cropped to exactly that ratio. size ("1080x1440", or a preset: uzum = 1080×1440,
instagram-post = 1080×1350, instagram-square, story = 1080×1920, youtube-thumbnail)
also resizes to the exact pixel size. The unprocessed original is kept in a raw/ subfolder.
Jobs, timeouts and retries
MCP bridges abandon a tool call after ~2 minutes, and a Gemini generation can take longer.
So every generation runs as a background job saved to output/jobs/<id>.json; any server
process can report on it. Pass an idempotency_key and a retry returns the earlier job or
result instead of making a duplicate. Every network step has a timeout: sign-in
(GEMINI_INIT_TIMEOUT, 45 s), the image download (90 s) and the whole job
(GEMINI_JOB_TIMEOUT, 300 s). Generations run one at a time per process
(GEMINI_MAX_CONCURRENT) so parallel calls don't trip Gemini's rate limits.
Publishing images to GitHub
Optionally, every generated or edited image can also be committed to a GitHub repository
of your choice (for example a public my-images repo), so you get a direct link you can
drop into websites, READMEs, or other projects:
https://raw.githubusercontent.com/<owner>/<repo>/<branch>/images/65157777b2c94e0f8d1a3c5e7f902468.jpgFiles are named by their gallery id, and commit messages carry only a short id, so your
prompts stay private even in a public repo (see GEMINI_GITHUB_INCLUDE_PROMPT below to
opt in to prompt-based names). Upload goes through the GitHub REST API, one commit per
image, so no local clone is needed. To turn it on, add to .env:
GEMINI_GITHUB_REPO=yourname/my-imagesToken -
GEMINI_GITHUB_TOKEN, elseGITHUB_TOKEN, else the GitHub CLI's login (gh auth token). Recommended: create a fine-grained token limited to that one repository with only Contents: read and write, and set it asGEMINI_GITHUB_TOKEN. Theghfallback is convenient but its token usually has fullrepoaccess to all your repositories, far more than this server needs.GEMINI_GITHUB_BRANCH- branch to commit to (default: the repo's default branch).GEMINI_GITHUB_PATH- folder inside the repo (default:images).GEMINI_GITHUB_AUTO_PUBLISH-false(default) publishes only when a call passespublish=trueor you use thepublish_imagetool;truepublishes every new image.GEMINI_GITHUB_INCLUDE_PROMPT-false(default). Set totrueto name files after the prompt (images/a-watercolor-fox-65157777.jpg) and put the prompt in the commit message. Remember that anything in a public repo, including its history, is public.Only images inside
output/images/can be published; any other path is refused.
You can also override per call ("generate ... and publish it"), and publish older
images later with publish_image. Published images show a Published badge in the
gallery with Copy link / Markdown buttons.
A publishing failure (bad token, network) never loses the image: it's still saved locally and added to the gallery, and the tool result explains what went wrong.
Raw links only work without authentication if the target repository is public. Keep in mind that anything you publish there is visible to everyone.
Using the core library directly
gemini_image_mcp.core is deliberately MCP-free, so it can be imported directly — for
example from a Telegram bot:
from gemini_image_mcp.config import get_settings
from gemini_image_mcp import core
async def handle_image_request(prompt: str) -> None:
settings = get_settings()
records = await core.generate_images(prompt, settings=settings)
for record in records:
absolute_path = settings.output_dir / record.image_path
# e.g. send `absolute_path` back to the Telegram chatTroubleshooting
Start with the built-in health check:
uv run gemini-image-mcp doctorIt checks, in order:
Check | What it looks at |
Output directory |
|
Cookie cache | The cache is outside the output folder (so sharing images never shares your session). |
Cookies |
|
Gemini sign-in | The cookies actually work, and how many models the account can use. |
Gallery | How many images the manifest holds, and whether a corrupt one was set aside. |
GitHub publishing | Where the token comes from, that it can push to the repo, and whether the repo is public. |
Each line is [ OK ], [WARN], [FAIL] or [SKIP] with a hint on how to fix it, and the
command exits with status 1 if anything failed. Add --offline to skip the calls to Gemini
and GitHub. Cookie and token values are never printed. You can also just ask Claude to "run
the doctor", which calls the doctor tool.
Auth / cookie expiry —
generate_image,edit_image, andlist_modelsall raise a clean error naming the exact problem whenGEMINI_1PSID/GEMINI_1PSIDTSare missing or have expired. Re-copy both values from Chrome DevTools (see above) and update.env(or the running process's environment)."No images returned" for a prompt that seems reasonable — this is almost always Gemini refusing the request (safety filter, region restriction, age-gating) rather than a bug. The error message includes the model's own text response, which usually explains the refusal directly.
Usage limits / temporarily blocked — Gemini's own rate limiting on the web app. Wait before retrying; there is no bypass.
GitHub publish failed - the tool result includes GitHub's message. 401/403 means the token is missing, expired, or lacks Contents write access to the repo; 404 means
GEMINI_GITHUB_REPOis wrong or the token can't see that repository.Where things live on disk — generated/edited images:
output/images/; the gallery:output/gallery.html; the manifest backing the gallery:output/manifest.json; the persisted cookie cache: whereverGEMINI_COOKIE_PATHpoints (default: a per-user folder outside the project, see Cookie lifetime; an oldoutput/.cookiescache is moved there automatically). All ofoutput/is gitignored.
Known limitations
Unofficial and fragile by nature. This drives a consumer web app that Google can change at any time without notice; a Google-side change can break this project until it's updated.
Region/age gated. Image generation availability depends on your Google account's region and age, not on this project.
Output format is whatever Gemini returns. Currently that's typically JPEG, regardless of the extension you might expect — this project sniffs the real format and corrects the file extension accordingly rather than trusting the request.
The manifest grows unbounded.
output/manifest.jsonaccumulates every record ever generated; there's no pruning or rotation.Not a daemon. The MCP server's lifetime is tied to the Claude session that launched it — it's not designed to run as a standalone, long-lived background service.
Contributing
See CONTRIBUTING.md.
Security
See SECURITY.md for the credential-handling model and how to report a vulnerability.
License
MIT — see the disclaimer above for the ToS and warranty caveats specific to this project; the MIT license text itself covers the standard no-warranty terms.
Available Tools
3 toolsedit_imageA
Edit one or more existing local image files using a text instruction.
image_paths must be paths to existing image files on disk (e.g. a photo or a
previously generated image) describing what to edit; prompt describes the desired
change. The edited image(s) Gemini returns are saved to disk and appended to the
cumulative HTML gallery; this tool returns the absolute paths of the new images plus
the gallery path so the result can be viewed.
Parameters
prompt: str
Instructions describing the desired edit.
image_paths: list[str]
Paths to existing local image files to edit.
model: str | None, optional
Model name/alias/id to use (see list_models). Defaults to the server's
configured default model, or the account's own default if unset.
Inputs: prompt (required), image_paths (required), model. Returns: result
generate_imageA
Generate one or more new images from a text prompt using the Gemini web app.
The prompt should describe the desired image in as much visual detail as helpful
(subject, style, composition, lighting, etc.) - it is sent to Gemini as an image
generation request. Newly generated images are saved to disk and appended to the
cumulative HTML gallery; this tool returns the absolute paths of the new images plus
the gallery path so the result can be viewed.
Parameters
prompt: str
A description of the image to generate.
model: str | None, optional
Model name/alias/id to use (see list_models). Defaults to the server's
configured default model, or the account's own default if unset.
Inputs: prompt (required), model. Returns: result
list_modelsA
List the Gemini models (image/chat) available to the currently signed-in account.
Returns each model's display name and internal model name/id, one per line. Use a
model_name value from this list as the model argument to generate_image or
edit_image to override the default model.
Inputs: no named parameters. Returns: result
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 serves a clearly distinct purpose: generate new images, edit existing images, and list available models. There is no meaningful overlap between these operations, so an agent can reliably select the right tool.
All tool names follow a consistent verb_noun pattern in snake_case: generate_image, list_models, edit_image. This creates a predictable and readable naming convention across the entire set.
Three tools is a well-scoped count for an image generation and editing server. Each tool covers a necessary core function without redundancy or unnecessary bloat.
The server covers the core image workflow: generating, editing, and choosing models. Minor gaps exist, such as no explicit gallery management or image deletion, but these are not essential to the stated purpose.
Related MCP Connectors
Generate images with your own ChatGPT subscription (Plus, Pro or Team), without spending API credits
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Generate, edit and upscale images with references, batch jobs, cost previews and original downloads.
Generate AI images, videos, music, SFX & speech in any AI assistant. Results appear inline in chat.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables chatting with Google Gemini AI models and custom Gems, supporting text and image generation with automatic cookie synchronization via Chrome extension.3-
- AlicenseAqualityCmaintenanceEnables AI image generation and editing using Google's Gemini Multimodal Image APIs.61MIT
- FlicenseNot gradedqualityDmaintenanceEnables image generation using Google Gemini models (flash/pro) with support for multiple sizes, reference images, and access control via Google OAuth and email allow-lists.1-
- AlicenseAqualityDmaintenanceEnables AI-powered image generation and editing using Google Gemini models, with support for transparency, reference images, and flexible output sizes.2MIT