@lensika/gemini-mcp

MCP server exposing Google Gemini image generation — both Imagen 4 and Gemini 2.5 Flash Image (Nano Banana) with Identity Locking via reference images.

What this fork adds over upstream [email protected]

| Capability | Upstream | This fork | |---|---|---| | Imagen 4 generation | yes | yes | | Gemini 2.5 Flash Image (Nano Banana) | no — wrong API method | yes | | Native text rendering inside images | partial (Imagen) | yes (Nano Banana) | | Identity Locking via reference photos | no input slot | yes — pass referenceImages | | Per-call model override on the tool | no | yes — pass model |

Install

npm install -g @lensika/gemini-mcp

Or invoke via npx -y @lensika/gemini-mcp --api-key "$GEMINI_API_KEY".

Register with Claude Code

claude mcp add --scope user gemini-mcp -- \
  npx -y @lensika/gemini-mcp --api-key "$GEMINI_API_KEY"

Or use the launcher script in lensika-core/scripts/hooks/gemini-mcp-launcher.sh.

Tools exposed

geminiGenerateImage

Returns image bytes as MCP image content.

{
  "prompt": "YouTube thumbnail, navy #004179 background, 'Stop Doing X' in orange #FF9E00, 16:9",
  "aspectRatio": "16:9",
  "numberOfImages": 2,
  "model": "gemini-2.5-flash-image",
  "referenceImages": ["~/lensika-core/skills/thumbnail-design/refs/wegaa/01.jpg"]
}

geminiGenerateImageToFile

Same inputs plus dstFilePath. Writes to disk. Use {id} in the path for multi-image runs.

Model selection

• model parameter on the tool call → highest priority
• GEMINI_IMAGE_MODEL env var → fallback default
• Hardcoded imagen-4.0-generate-001 → final fallback

Routing: model name starting with gemini- and containing image → Gemini path (generateContent). Otherwise → Imagen path (generateImages).

Identity Locking

Pass 1–3 photos of the subject as referenceImages. Each entry can be:

• An absolute path: /Users/.../wegaa/01.jpg
• A ~-prefixed path: ~/lensika-core/skills/thumbnail-design/refs/wegaa/01.jpg
• A raw base64 string of the image bytes

Only honored when model is a Gemini image model. Imagen calls reject referenceImages with a clear error.

License

MIT — see LICENSE and NOTICE for attribution.