@chrischall/gemini-mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,86 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadDotenvSafely, readEnvVar, McpToolError, truncateErrorMessage } from '@chrischall/mcp-utils';
+import { resolveModel, filterImageModels } from './models.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
+const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'; // v1 lacks gemini-3-pro-image; confirmed via Task 5
+const SERVICE = 'Gemini';
+export class GeminiClient {
+    apiKey;
+    configError;
+    fetchImpl;
+    constructor(opts = {}) {
+        const key = readEnvVar('GEMINI_API_KEY');
+        if (!key) {
+            this.apiKey = null;
+            this.configError = new McpToolError('GEMINI_API_KEY environment variable is required', {
+                hint: 'Create a key at https://aistudio.google.com/apikey and set GEMINI_API_KEY in your MCP host env or .env',
+            });
+        }
+        else {
+            this.apiKey = key;
+            this.configError = null;
+        }
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    requireKey() {
+        if (this.configError)
+            throw this.configError;
+        return this.apiKey;
+    }
+    /** The default model after env override (no per-call arg). */
+    defaultModel() {
+        return resolveModel(undefined, readEnvVar('GEMINI_IMAGE_MODEL'));
+    }
+    async call(method, path, body) {
+        const key = this.requireKey();
+        const res = await this.fetchImpl(`${BASE_URL}${path}`, {
+            method,
+            headers: { 'x-goog-api-key': key, 'content-type': 'application/json' },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new McpToolError(`${SERVICE} API ${res.status}: ${truncateErrorMessage(text)}`);
+        }
+        return (await res.json());
+    }
+    async listModels() {
+        const data = await this.call('GET', '/models?pageSize=200');
+        return filterImageModels(data.models ?? []);
+    }
+    async generate(opts) {
+        const model = resolveModel(opts.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        const parts = [{ text: opts.prompt }];
+        for (const img of opts.images ?? []) {
+            parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
+        }
+        const generationConfig = { responseModalities: ['IMAGE'] };
+        if (opts.aspectRatio || opts.imageSize) {
+            const imageConfig = {};
+            if (opts.aspectRatio)
+                imageConfig.aspectRatio = opts.aspectRatio;
+            if (opts.imageSize)
+                imageConfig.imageSize = opts.imageSize;
+            generationConfig.imageConfig = imageConfig;
+        }
+        const data = await this.call('POST', `/models/${model}:generateContent`, { contents: [{ parts }], generationConfig });
+        const out = [];
+        for (const cand of data.candidates ?? []) {
+            for (const part of cand.content?.parts ?? []) {
+                const inline = (part.inline_data ?? part.inlineData);
+                if (inline?.data)
+                    out.push({ base64: inline.data, mimeType: inline.mime_type ?? inline.mimeType ?? 'image/jpeg' });
+            }
+        }
+        if (out.length === 0) {
+            throw new McpToolError(`${SERVICE} returned no image`, {
+                hint: 'The request may have been blocked by safety filters — try rephrasing the prompt.',
+            });
+        }
+        return out;
+    }
+}
+/** Module-level singleton shared by every tool module (deferred-config-error). */
+export const client = new GeminiClient();

package/dist/images.js

@@ -0,0 +1,51 @@
+import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { readEnvVar } from '@chrischall/mcp-utils';
+/** URL/file-safe slug from a prompt; never empty. */
+export function slugify(text, max = 40) {
+    const s = text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, max)
+        .replace(/-+$/g, '');
+    return s || 'image';
+}
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `<base>.<ext>`, then `<base>-2.<ext>`, … until a free path is found. */
+export async function uniquePath(dir, base, ext) {
+    let candidate = join(dir, `${base}.${ext}`);
+    let n = 2;
+    while (await exists(candidate)) {
+        candidate = join(dir, `${base}-${n}.${ext}`);
+        n++;
+    }
+    return candidate;
+}
+/** Decode base64 image bytes and write to disk (creating dir). Returns the path. */
+export async function writeImage(dir, base, base64, mimeType) {
+    await mkdir(dir, { recursive: true });
+    const ext = mimeType.includes('jpeg') ? 'jpg' : 'png';
+    const path = await uniquePath(dir, base, ext);
+    await writeFile(path, Buffer.from(base64, 'base64'));
+    return path;
+}
+/** Read an image file into `{ base64, mimeType }` for an inline_data part. */
+export async function readImageAsInline(path) {
+    const buf = await readFile(path);
+    const lower = path.toLowerCase();
+    const mimeType = lower.endsWith('.jpg') || lower.endsWith('.jpeg') ? 'image/jpeg' : 'image/png';
+    return { base64: buf.toString('base64'), mimeType };
+}
+/** per-call → $GEMINI_OUTPUT_DIR → cwd. */
+export function resolveOutputDir(perCall) {
+    return perCall?.trim() || readEnvVar('GEMINI_OUTPUT_DIR') || process.cwd();
+}

package/dist/index.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { runMcp } from '@chrischall/mcp-utils';
+import { VERSION } from './version.js';
+import { registerModelTools } from './tools/models.js';
+import { registerGenerateTools } from './tools/generate.js';
+import { registerSetTools } from './tools/set.js';
+// The GeminiClient is a module-level singleton (imported by each tool module)
+// that defers its config error to the first request — so the server boots and
+// answers the host's install-time tools/list probe even without GEMINI_API_KEY.
+await runMcp({
+    name: 'gemini-mcp',
+    version: VERSION,
+    banner: '[gemini-mcp] This project was developed and is maintained by AI (Claude). Use at your own discretion.',
+    tools: [registerModelTools, registerGenerateTools, registerSetTools],
+});

package/dist/models.js

@@ -0,0 +1,20 @@
+/** Latest top-end image model; overridable per-call and via GEMINI_IMAGE_MODEL. */
+export const DEFAULT_IMAGE_MODEL = 'gemini-3-pro-image';
+/** Per-call → env override → hardcoded default. Blank/whitespace counts as unset. */
+export function resolveModel(perCall, envOverride) {
+    return perCall?.trim() || envOverride?.trim() || DEFAULT_IMAGE_MODEL;
+}
+/**
+ * Keep only Gemini image-generation models (the Nano Banana family) and strip
+ * the `models/` prefix. Excludes `imagen-*` — those contain the substring
+ * "image" but use a different `:predict` API this server doesn't implement.
+ */
+export function filterImageModels(raw) {
+    return raw
+        .filter((m) => /image/i.test(m.name ?? '') && !/imagen/i.test(m.name ?? ''))
+        .map((m) => ({
+        id: (m.name ?? '').replace(/^models\//, ''),
+        displayName: m.displayName ?? '',
+        description: m.description ?? '',
+    }));
+}

package/dist/tools/generate.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { client } from '../client.js';
+import { slugify, readImageAsInline } from '../images.js';
+import { emit, sharedImageSchema } from './shared.js';
+export function registerGenerateTools(server) {
+    server.registerTool('gemini_generate_image', {
+        description: 'Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro).',
+        annotations: { readOnlyHint: false, openWorldHint: true },
+        inputSchema: {
+            prompt: z.string().min(1).describe('Text prompt describing the image'),
+            count: z.number().int().positive().max(8).optional().describe('Number of independent images (default 1)'),
+            ...sharedImageSchema,
+        },
+    }, async (args) => {
+        const count = args.count ?? 1;
+        const slug = slugify(args.prompt);
+        const named = [];
+        for (let i = 0; i < count; i++) {
+            const [img] = await client.generate({
+                prompt: args.prompt,
+                model: args.model,
+                aspectRatio: args.aspect_ratio,
+                imageSize: args.image_size,
+            });
+            named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, '0')}` });
+        }
+        return emit(named, args);
+    });
+    server.registerTool('gemini_edit_image', {
+        description: 'Edit or compose images: provide one image to edit, or multiple images to combine/blend, plus a text instruction.',
+        annotations: { readOnlyHint: false, openWorldHint: true },
+        inputSchema: {
+            prompt: z.string().min(1).describe('Instruction describing the edit or composition'),
+            images: z.array(z.string().min(1)).min(1).describe('Paths to input image file(s) (1 = edit, 2+ = compose)'),
+            ...sharedImageSchema,
+        },
+    }, async (args) => {
+        const inputs = await Promise.all(args.images.map((p) => readImageAsInline(p)));
+        const [img] = await client.generate({
+            prompt: args.prompt,
+            images: inputs,
+            model: args.model,
+            aspectRatio: args.aspect_ratio,
+            imageSize: args.image_size,
+        });
+        return emit([{ image: img, base: slugify(args.prompt) }], args);
+    });
+}

package/dist/tools/models.js

@@ -0,0 +1,11 @@
+import { textResult } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+export function registerModelTools(server) {
+    server.registerTool('gemini_list_models', {
+        description: 'List the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.',
+        annotations: { readOnlyHint: true },
+    }, async () => {
+        const models = await client.listModels();
+        return textResult({ default: client.defaultModel(), models });
+    });
+}

package/dist/tools/set.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { McpToolError } from '@chrischall/mcp-utils';
+import { client } from '../client.js';
+import { slugify } from '../images.js';
+import { emit, sharedImageSchema } from './shared.js';
+export function registerSetTools(server) {
+    server.registerTool('gemini_generate_set', {
+        description: 'Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master).',
+        annotations: { readOnlyHint: false, openWorldHint: true },
+        inputSchema: {
+            master_prompt: z.string().min(1).describe('Prompt for the master/reference image'),
+            scenes: z.array(z.string().min(1)).min(1).max(8).optional().describe('Per-image prompts (1-8); each references the master'),
+            count: z.number().int().positive().max(8).optional().describe('Number of variations of master_prompt (when scenes omitted)'),
+            reference_mode: z.enum(['master', 'chain']).optional().describe('master: every image references the master (default). chain: each references the previous.'),
+            ...sharedImageSchema,
+        },
+    }, async (args) => {
+        // `scenes` is min(1) at the schema, so a non-undefined value is non-empty.
+        if ((args.scenes && args.count) || (!args.scenes && !args.count)) {
+            throw new McpToolError('Provide exactly one of `scenes` or `count`.');
+        }
+        const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size };
+        const slug = slugify(args.master_prompt);
+        // 1. master
+        const [master] = await client.generate({ prompt: args.master_prompt, ...cfg });
+        const named = [{ image: master, base: `${slug}-master` }];
+        // 2. scene prompts (explicit, or N repeats of master_prompt for variations)
+        const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
+        const mode = args.reference_mode ?? 'master';
+        if (mode === 'chain') {
+            let ref = master;
+            for (let i = 0; i < scenePrompts.length; i++) {
+                const [img] = await client.generate({ prompt: scenePrompts[i], images: [ref], ...cfg });
+                named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` });
+                ref = img;
+            }
+        }
+        else {
+            const scenes = await Promise.all(scenePrompts.map((p) => client.generate({ prompt: p, images: [master], ...cfg }).then((r) => r[0])));
+            scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` }));
+        }
+        return emit(named, args);
+    });
+}

package/dist/tools/shared.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { textResult } from '@chrischall/mcp-utils';
+import { writeImage, resolveOutputDir } from '../images.js';
+/** Supported output aspect ratios (Gemini image API). */
+export const ASPECT_RATIOS = ['1:1', '2:3', '3:2', '3:4', '4:3', '4:5', '5:4', '9:16', '16:9', '21:9', '1:4', '4:1', '1:8', '8:1'];
+/** Supported output resolutions. */
+export const IMAGE_SIZES = ['1K', '2K', '4K'];
+/**
+ * The model/aspect/size/output fields every generation tool shares. Defined once
+ * here so descriptions can't drift between `generate.ts` and `set.ts`. Spread
+ * into each tool's `inputSchema`.
+ */
+export const sharedImageSchema = {
+    model: z.string().optional().describe('Model id override (default: server default; see gemini_list_models)'),
+    aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('Output aspect ratio'),
+    image_size: z.enum(IMAGE_SIZES).optional().describe('Output resolution'),
+    output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
+    inline: z.boolean().optional().describe('Return base64 images inline instead of writing to disk'),
+};
+/**
+ * Either return images inline (base64 content blocks) or write them to disk and
+ * return their paths as a text result. `inline` wins when true.
+ */
+export async function emit(named, opts) {
+    if (opts.inline) {
+        return {
+            content: named.map((n) => ({ type: 'image', data: n.image.base64, mimeType: n.image.mimeType })),
+        };
+    }
+    const dir = resolveOutputDir(opts.output_dir);
+    const images = [];
+    for (const n of named)
+        images.push(await writeImage(dir, n.base, n.image.base64, n.image.mimeType));
+    return textResult({ images });
+}

package/dist/version.js

@@ -0,0 +1,2 @@
+/** Single source of the server version. release-please bumps the literal below. */
+export const VERSION = '0.1.0'; // x-release-please-version

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@chrischall/gemini-mcp",
+  "version": "0.1.0",
+  "mcpName": "io.github.chrischall/gemini-mcp",
+  "description": "Gemini image-generation MCP server for Claude — developed and maintained by AI (Claude Code)",
+  "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
+  "repository": { "type": "git", "url": "git+https://github.com/chrischall/gemini-mcp.git" },
+  "license": "MIT",
+  "keywords": ["mcp", "model-context-protocol", "claude", "ai", "gemini", "nano-banana", "image-generation", "image-editing", "text-to-image", "google-gemini"],
+  "type": "module",
+  "publishConfig": { "access": "public" },
+  "bin": { "gemini-mcp": "dist/index.js" },
+  "files": ["dist", ".claude-plugin", "SKILL.md", ".mcp.json", "server.json"],
+  "scripts": {
+    "build": "tsc && npm run bundle",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --external:dotenv --outfile=dist/bundle.js",
+    "dev": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@chrischall/mcp-utils": "^0.6.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "dotenv": "^17.4.0",
+    "zod": "^4.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "@vitest/coverage-v8": "^4.1.2",
+    "esbuild": "^0.28.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  }
+}

package/server.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.chrischall/gemini-mcp",
+  "description": "Generate and edit images with Google Gemini (Nano Banana / Nano Banana Pro) image models.",
+  "repository": {
+    "url": "https://github.com/chrischall/gemini-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@chrischall/gemini-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "GEMINI_API_KEY",
+          "description": "Your Google Gemini API key (aistudio.google.com/apikey)",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": true
+        },
+        {
+          "name": "GEMINI_IMAGE_MODEL",
+          "description": "Override the default image model (default: gemini-3-pro-image)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        },
+        {
+          "name": "GEMINI_OUTPUT_DIR",
+          "description": "Default directory for generated images (default: current working directory)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}