NanoBridge

NanoBridge

Gemini's Nano Banana image generation, wired into agents as an MCP serverand a CLI — using the Gemini plan the account already has, not a per-imagebill.

nanobridge sprite "a small knight with a blue shield and a silver sword" --size 160

Both of those came out of the commands in this README — the sprite alreadytrimmed and transparent, the animation already sliced from a sheet and assembledinto a looping GIF.

Why not just call the API

The AI Studio API key is the obvious route and it does not work on a free plan:every image model answers 429 RESOURCE_EXHAUSTED, because the free tier grantszero image quota. Enabling billing fixes it and starts charging per image, whilethe Gemini subscription already sitting on the same account goes unused.

NanoBridge takes the other door: it authenticates as the browser does, with the__Secure-1PSID cookie already in Chrome, and spends the subscription's quota.Nothing to paste, nothing to buy.

nanobridge doctor reports which one is live and how much quota is left.

Install

git clone https://github.com/NspxMiguel/NanoBridge.git
cd NanoBridge && ./install.sh

The installer builds a virtualenv, puts nanobridge on PATH, registers the MCPserver with Claude Code, and installs the agent skill. Homebrew:

brew install --cask nspxmiguel/tap/nanobridge

Requirements: Python 3.11+, and a browser signed in tohttps://gemini.google.com.

Use it from the shell

nanobridge doctor                        # backends, quota, config path
nanobridge sprite "a green slime" --style pixel --size 128
nanobridge icon "a compass rose" --style flat
nanobridge gen "a seamless stone wall texture, top-down, tileable"
nanobridge edit hero.png "make the sky stormy, keep everything else"

nanobridge sheet "a green slime" --grid 4x2 \
  --action "squash down and stretch back up, a bouncy idle loop" --fps 10

Sheets are generated, sliced into frames, and assembled into a looping GIF withthe transparency preserved — GIF has no alpha channel, so a palette index isreserved for the empty pixels.

Two commands never touch the network, so they cost no quota and work on imagesfrom anywhere:

nanobridge cut photo.jpg --transparent --trim --size 256
nanobridge slice sheet.png --grid 6x1 --size 96

Use it from an agent

The MCP server exposes generate_image, generate_sprite,generate_sprite_sheet, generate_icon, edit_image, cut_image,slice_sheet and nanobridge_status.

Every generating tool returns the image back to the model, downscaled to a512px preview, alongside the paths on disk. That is the point: an agent thatcannot see what it drew cannot tell a good sprite from a broken one, and iteratesblind.

Registering it by hand:

claude mcp add nanobridge --scope user -- /path/to/.venv/bin/nanobridge mcp

What the post-processing does

The model returns a large JPEG on a flat background. Sprites need the opposite,so the pipeline is part of the tool rather than an afterthought:

• Background removal is border-connected, not colour-matched. A white eyeinside a sprite has the same colour as the white behind it; only the regionthat reaches the image border is erased.
• Trim crops to the drawing.
• Resize is nearest-neighbour. Pixel art resampled with a smooth filter stopslooking like pixel art.
• Slicing is geometric. The grid asked for in the prompt is the grid used tocut, and the individual frames are written out — that is where you see whetherthe model actually obeyed.

Languages

Screen text is Portuguese and English. The system locale picks the default,nanobridge lang pt|en saves a choice, and NANOBRIDGE_LANG=pt overrides bothfor one run.

Limits worth knowing

• The web backend depends on a browser session. When it expires, sign in again athttps://gemini.google.com; nanobridge doctor says so explicitly.
• It talks to an interface Google does not document, so a change on their side canbreak it. The api backend is the fallback that stays put.
• Generated images carry Google's SynthID watermark.

License

MIT.