@falldownthesystem/imagen-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FallDownTheSystem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,99 @@
+# imagen-mcp
+
+Minimal MCP server for OpenAI GPT Image 2.5. Two tools, two models.
+
+| Alias | API model | Use |
+|---|---|---|
+| `flare` (default) | `gpt-image-2.5-flare` | Fast, general purpose |
+| `sunburst` | `gpt-image-2.5-sunburst` | Slower, higher precision |
+
+## Setup
+
+Install from npm:
+
+```sh
+npm install -g @falldownthesystem/imagen-mcp
+```
+
+Or build from source:
+
+```sh
+npm install
+npm run build
+```
+
+Set `OPENAI_API_KEY` in the environment, or put it in a `.env` file next to `package.json`.
+
+Optional environment variables:
+
+- `IMAGEN_OUTPUT_DIR`: default directory for saved images (default `./output`).
+- `IMAGEN_DEFAULT_MODEL`: `flare` or `sunburst` (default `flare`).
+
+## Client config
+
+Claude Code (`.mcp.json`) or Claude Desktop, using the npm package:
+
+```json
+{
+	"mcpServers": {
+		"imagen": {
+			"command": "npx",
+			"args": ["-y", "@falldownthesystem/imagen-mcp"],
+			"env": {
+				"OPENAI_API_KEY": "sk-...",
+				"IMAGEN_OUTPUT_DIR": "C:/Users/me/Pictures/imagen"
+			}
+		}
+	}
+}
+```
+
+Or with a local build, use `"command": "node"` and `"args": ["path/to/imagen-mcp/dist/index.js"]`.
+
+Claude Code one-liner:
+
+```sh
+claude mcp add imagen -e OPENAI_API_KEY=sk-... -- npx -y @falldownthesystem/imagen-mcp
+```
+
+## Tools
+
+### `generate_image`
+
+Text to image. Required: `prompt`.
+
+| Option | Values | Default | Notes |
+|---|---|---|---|
+| `moderation` | `auto`, `low` | `low` | OpenAI content filter strictness. `low` refuses fewer borderline prompts; OpenAI usage policies still apply. The API default is `auto`; this tool sends `low` unless set. |
+
+### `edit_image`
+
+Reference images to image. Required: `prompt`, `images`. The model regenerates the whole picture guided by the references and the prompt. Without a mask, the prompt alone decides what changes.
+
+| Option | Values | Default | Notes |
+|---|---|---|---|
+| `images` | 1 to 16 file paths | required | `png`, `jpeg`, or `webp`. The first image is the main subject; extra images supply elements to combine, such as a logo or a style reference. Relative paths resolve against the server working directory. |
+| `mask` | file path | none | PNG with an alpha channel, same width and height as the first image. Fully transparent pixels mark the region the model may repaint; opaque pixels mark what to keep. Use for inpainting one area or filling an extended canvas. It is guidance, not a hard pixel lock. |
+| `input_fidelity` | `high`, `low` | `low` | How closely exact details from the references are preserved. `low` keeps content and layout, but faces, text, logos, and textures may shift. `high` keeps them faithful and steadies the area outside a mask. It costs more input tokens per reference image. Use `high` for real people, brands, product shots, or spot edits. |
+
+### Shared options
+
+Only the options you set are sent to the API. The default column shows what applies when an option is omitted.
+
+| Option | Values | Default | Notes |
+|---|---|---|---|
+| `prompt` | text, up to 32000 chars | required | |
+| `model` | `flare`, `sunburst` | `flare` | `flare` (`gpt-image-2.5-flare`) is fast and general purpose. `sunburst` (`gpt-image-2.5-sunburst`) is slower with higher precision. Same token price. `IMAGEN_DEFAULT_MODEL` env changes the default. |
+| `size` | `auto`, `1024x1024`, `1536x1024`, `1024x1536`, `WIDTHxHEIGHT` | `auto` | Custom sizes: multiples of 16, ratio 1:3 to 3:1, long edge up to 3840. Overrides `aspect_ratio`. |
+| `aspect_ratio` | `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, `9:21` | none | Combined with `long_edge` to compute a size. |
+| `long_edge` | 256 to 3840 | 1536 | Only used with `aspect_ratio`. |
+| `quality` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` | `auto` | Higher tiers add detail and cost more output tokens. `auto` lets the model choose and may pick an expensive tier. Set it explicitly to control cost. |
+| `background` | `transparent`, `opaque`, `auto` | `auto` | `transparent` gives an alpha background for stickers, logos, and cut-outs. Needs `png` or `webp`. |
+| `output_format` | `png`, `jpeg`, `webp` | `png` | Also sets the file extension. |
+| `output_compression` | 0 to 100 | 100 | `jpeg` and `webp` only. Works like JPEG quality: lower is smaller with more artifacts. |
+| `n` | 1 to 10 | 1 | Number of separate variations generated from the same prompt in one call. Each costs its own output tokens. |
+| `output_dir` | directory path | `IMAGEN_OUTPUT_DIR` env, else `./output` | Relative to the server working directory. |
+| `file_name` | base name without extension | timestamp plus a slug of the prompt | With `n` greater than 1, a `-1`, `-2` suffix is added. |
+| `return_image` | boolean | `false` | Also return each image inline as MCP image content, so the client shows it and the model can inspect it. Adds about 1.4 MB of context per 1024x1024 png. The file is saved to disk either way. |
+
+The result lists the saved file paths, the model, the size, and token usage.

package/dist/index.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import path from "node:path";
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import OpenAI, { toFile } from "openai";
+import * as z from "zod/v4";
+import { commonInput, resolveModel, resolveSize } from "./params.js";
+// A .env next to the project is a convenience for local runs; MCP client configs normally pass env directly.
+try {
+    process.loadEnvFile(path.join(import.meta.dirname, "..", ".env"));
+}
+catch {
+    // No .env file present; rely on the process environment.
+}
+const client = new OpenAI();
+const server = new McpServer({ name: "imagen-mcp", version: "0.1.0" });
+const MIME = { png: "image/png", jpeg: "image/jpeg", webp: "image/webp" };
+const outputSchema = z.object({
+    files: z.array(z.string()),
+    model: z.string(),
+    size: z.string(),
+    usage: z
+        .object({
+        input_tokens: z.number(),
+        output_tokens: z.number(),
+        total_tokens: z.number(),
+        input_tokens_details: z.object({ image_tokens: z.number(), text_tokens: z.number() }).optional(),
+        output_tokens_details: z.object({ image_tokens: z.number(), text_tokens: z.number() }).optional(),
+    })
+        .optional(),
+});
+const annotations = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+function slug(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "image";
+}
+function apiParams(input) {
+    return {
+        model: resolveModel(input.model),
+        prompt: input.prompt,
+        size: resolveSize(input),
+        quality: input.quality,
+        background: input.background,
+        output_format: input.output_format,
+        output_compression: input.output_compression,
+        n: input.n,
+    };
+}
+async function saveImages(result, input, model, size) {
+    const images = result.data ?? [];
+    if (images.length === 0)
+        throw new Error("The API returned no images.");
+    const ext = input.output_format ?? "png";
+    const dir = path.resolve(input.output_dir ?? process.env.IMAGEN_OUTPUT_DIR ?? "output");
+    await fs.mkdir(dir, { recursive: true });
+    const base = input.file_name ?? `${new Date().toISOString().replace(/[:.]/g, "-")}-${slug(input.prompt)}`;
+    const files = [];
+    const content = [];
+    for (const [i, image] of images.entries()) {
+        if (!image.b64_json)
+            throw new Error(`Image ${i + 1} has no b64_json payload.`);
+        const file = path.join(dir, images.length > 1 ? `${base}-${i + 1}.${ext}` : `${base}.${ext}`);
+        await fs.writeFile(file, Buffer.from(image.b64_json, "base64"));
+        files.push(file);
+        if (input.return_image)
+            content.push({ type: "image", data: image.b64_json, mimeType: MIME[ext] });
+    }
+    const output = { files, model, size: size ?? "auto", usage: result.usage };
+    content.unshift({ type: "text", text: JSON.stringify(output, null, 2) });
+    return { content, structuredContent: output };
+}
+async function loadImage(file) {
+    const abs = path.resolve(file);
+    const ext = path.extname(abs).slice(1).toLowerCase();
+    const type = MIME[ext === "jpg" ? "jpeg" : ext] ?? "application/octet-stream";
+    return toFile(await fs.readFile(abs), path.basename(abs), { type });
+}
+server.registerTool("generate_image", {
+    title: "Generate image",
+    description: "Generate images from a text prompt with OpenAI GPT Image 2.5. Saves files to disk and returns paths and token usage.",
+    inputSchema: z.object({
+        ...commonInput,
+        moderation: z
+            .enum(["auto", "low"])
+            .optional()
+            .describe("OpenAI content filter. low refuses fewer borderline prompts. Default low."),
+    }),
+    outputSchema,
+    annotations,
+}, async (input) => {
+    const params = apiParams(input);
+    const result = await client.images.generate({ ...params, moderation: input.moderation ?? "low" });
+    return saveImages(result, input, params.model, params.size);
+});
+server.registerTool("edit_image", {
+    title: "Edit image",
+    description: "Edit, restyle, or combine 1-16 reference images with a text prompt using OpenAI GPT Image 2.5. The whole picture is regenerated; without a mask the prompt decides what changes. Saves files to disk and returns paths and token usage.",
+    inputSchema: z.object({
+        ...commonInput,
+        images: z
+            .array(z.string())
+            .min(1)
+            .max(16)
+            .describe("Paths of 1-16 reference images (png/jpeg/webp). First = main subject; others = elements to combine. Relative to server cwd."),
+        mask: z
+            .string()
+            .optional()
+            .describe("Path of a PNG with alpha, same size as first image. Transparent pixels = region to repaint (guidance, not a hard lock). Default none."),
+        input_fidelity: z
+            .enum(["high", "low"])
+            .optional()
+            .describe("high keeps faces, text, logos and unmasked areas faithful; costs more input tokens. Default low."),
+    }),
+    outputSchema,
+    annotations,
+}, async (input) => {
+    const params = apiParams(input);
+    const result = await client.images.edit({
+        ...params,
+        image: await Promise.all(input.images.map(loadImage)),
+        mask: input.mask ? await loadImage(input.mask) : undefined,
+        input_fidelity: input.input_fidelity,
+    });
+    return saveImages(result, input, params.model, params.size);
+});
+await server.connect(new StdioServerTransport());

package/dist/params.js

@@ -0,0 +1,110 @@
+import * as z from "zod/v4";
+export const MODELS = {
+    flare: "gpt-image-2.5-flare",
+    sunburst: "gpt-image-2.5-sunburst",
+};
+const ASPECT_RATIOS = {
+    "1:1": 1,
+    "3:2": 3 / 2,
+    "2:3": 2 / 3,
+    "4:3": 4 / 3,
+    "3:4": 3 / 4,
+    "16:9": 16 / 9,
+    "9:16": 9 / 16,
+    "21:9": 21 / 9,
+    "9:21": 9 / 21,
+};
+// Limits documented by OpenAI for custom WIDTHxHEIGHT sizes on GPT Image models.
+const SIZE_STEP = 16;
+const MAX_LONG_EDGE = 3840;
+const MAX_RATIO = 3;
+const DEFAULT_LONG_EDGE = 1536;
+export const commonInput = {
+    prompt: z
+        .string()
+        .min(1)
+        .max(32000)
+        .describe("Image description, or the change to make when editing."),
+    model: z
+        .enum(["flare", "sunburst"])
+        .optional()
+        .describe("flare = fast, general purpose. sunburst = slower, higher precision. Same price. Default flare."),
+    size: z
+        .string()
+        .regex(/^(auto|\d+x\d+)$/)
+        .optional()
+        .describe("auto | 1024x1024 | 1536x1024 | 1024x1536 | WIDTHxHEIGHT (multiples of 16, ratio 1:3..3:1, max edge 3840). Overrides aspect_ratio. Default auto."),
+    aspect_ratio: z
+        .enum(Object.keys(ASPECT_RATIOS))
+        .optional()
+        .describe("Computes size together with long_edge. Default none."),
+    long_edge: z
+        .number()
+        .int()
+        .min(256)
+        .max(MAX_LONG_EDGE)
+        .optional()
+        .describe(`Longer side in px, used with aspect_ratio. Default ${DEFAULT_LONG_EDGE}.`),
+    quality: z
+        .enum(["low", "medium", "high", "xhigh", "max", "auto"])
+        .optional()
+        .describe("Higher = more detail, more output tokens. auto lets the model choose (may be costly). Default auto."),
+    background: z
+        .enum(["transparent", "opaque", "auto"])
+        .optional()
+        .describe("transparent needs png or webp. Default auto."),
+    output_format: z.enum(["png", "jpeg", "webp"]).optional().describe("Also the file extension. Default png."),
+    output_compression: z
+        .number()
+        .int()
+        .min(0)
+        .max(100)
+        .optional()
+        .describe("jpeg/webp quality like JPEG: lower = smaller file, more artifacts. Default 100."),
+    n: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .optional()
+        .describe("Number of variations to generate; each costs output tokens. Files get -1, -2 suffixes. Default 1."),
+    output_dir: z.string().optional().describe("Save directory. Default IMAGEN_OUTPUT_DIR env or ./output (relative to server cwd)."),
+    file_name: z.string().optional().describe("Base name without extension. Default timestamp + prompt slug."),
+    return_image: z
+        .boolean()
+        .optional()
+        .describe("Also return the image inline (base64, ~1.4 MB per 1024x1024 png) so it can be viewed. File is saved either way. Default false."),
+};
+export function resolveModel(alias) {
+    const fallback = process.env.IMAGEN_DEFAULT_MODEL;
+    return MODELS[alias ?? fallback ?? "flare"] ?? MODELS.flare;
+}
+function roundToStep(value) {
+    return Math.max(SIZE_STEP, Math.round(value / SIZE_STEP) * SIZE_STEP);
+}
+function validateSize(size) {
+    if (size === "auto")
+        return size;
+    const [w, h] = size.split("x").map(Number);
+    if (w % SIZE_STEP !== 0 || h % SIZE_STEP !== 0) {
+        throw new Error(`size ${size}: width and height must be multiples of ${SIZE_STEP}.`);
+    }
+    if (Math.max(w, h) > MAX_LONG_EDGE) {
+        throw new Error(`size ${size}: long edge must be <= ${MAX_LONG_EDGE}.`);
+    }
+    const ratio = w / h;
+    if (ratio > MAX_RATIO || ratio < 1 / MAX_RATIO) {
+        throw new Error(`size ${size}: aspect ratio must be between 1:${MAX_RATIO} and ${MAX_RATIO}:1.`);
+    }
+    return size;
+}
+export function resolveSize(input) {
+    if (input.size)
+        return validateSize(input.size);
+    if (!input.aspect_ratio)
+        return undefined;
+    const ratio = ASPECT_RATIOS[input.aspect_ratio];
+    const long = roundToStep(input.long_edge ?? DEFAULT_LONG_EDGE);
+    const short = roundToStep(long / Math.max(ratio, 1 / ratio));
+    return ratio >= 1 ? `${long}x${short}` : `${short}x${long}`;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@falldownthesystem/imagen-mcp",
+	"version": "0.1.0",
+	"description": "Minimal MCP server for OpenAI GPT Image 2.5 (flare and sunburst): generate and edit images",
+	"type": "module",
+	"bin": {
+		"imagen-mcp": "dist/index.js"
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsc",
+		"start": "node dist/index.js",
+		"dev": "tsc --watch",
+		"prepublishOnly": "npm run build"
+	},
+	"engines": {
+		"node": ">=22"
+	},
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"openai",
+		"gpt-image",
+		"image-generation"
+	],
+	"author": "FallDownTheSystem",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/FallDownTheSystem/imagen-mcp.git"
+	},
+	"homepage": "https://github.com/FallDownTheSystem/imagen-mcp#readme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/server": "^2.0.0",
+		"openai": "^7.13.0",
+		"zod": "^4.5.4"
+	},
+	"devDependencies": {
+		"@types/node": "^26.5.0",
+		"typescript": "^7.0.2"
+	}
+}