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_image and edit_image MCP tools backed by your own Gemini web session — no API key, no per-image billing.

• list_models to discover which models your account can use.

• 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.core has zero mcp imports, 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. .jpg instead of a mislabeled .png).

Requirements

• Python >= 3.11

• uv

• 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 sync

copy .env.example .env

Edit .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

1. 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.

2. Press F12 to open Chrome DevTools.

3. Go to the Application tab -> Storage -> Cookies -> https://gemini.google.com.

4. Find the cookie named __Secure-1PSID. Click it and copy its Value column (a long string). This is your GEMINI_1PSID.

5. Find the cookie named __Secure-1PSIDTS. Copy its Value the same way. This is your GEMINI_1PSIDTS.

6. Copy .env.example to .env and paste the two values into GEMINI_1PSID and GEMINI_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.

• GEMINI_COOKIE_SOURCE - auto (default: .env values if set, else the browsers above, also used as a fallback when the .env values 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 (for auto, it applies to Firefox). GEMINI_FIREFOX_COOKIE_FILE still 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

None of the tools return base64 image data — the gallery is the intended viewing surface, and every tool result includes its path so you can always click through to it.

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.jpg

Files 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-images

• Token - GEMINI_GITHUB_TOKEN, else GITHUB_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 as GEMINI_GITHUB_TOKEN. The gh fallback is convenient but its token usually has full repo access 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 passes publish=true or you use the publish_image tool; true publishes every new image.

• GEMINI_GITHUB_INCLUDE_PROMPT - false (default). Set to true to 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 chat

Troubleshooting

Start with the built-in health check:

uv run gemini-image-mcp doctor

It checks, in order:

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, and list_models all raise a clean error naming the exact problem when GEMINI_1PSID/GEMINI_1PSIDTS are 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_REPO is 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: wherever GEMINI_COOKIE_PATH points (default: a per-user folder outside the project, see Cookie lifetime; an old output/.cookies cache is moved there automatically). All of output/ 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.json accumulates 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.