Gemini Image MCP

Instructions

Implementation Reference

• gemini-image.js:114-157 (handler)

  Core generateImage function that generates images using Google's Gemini AI API. Takes a prompt and options (outputPath, aspectRatio, imageSize, model), calls the API, extracts the image data from the response, saves it to a file, and returns the result with success status.

  export async function generateImage(prompt, options = {}) {
    const ai = getAI();
    const model = options.model || DEFAULT_MODEL;
    const outputPath = resolveOutput(
      options.output || options.outputPath || "./generated.png"
    );
  
    const config = buildConfig(options);
  
    try {
      const response = await ai.models.generateContent({
        model,
        contents: prompt,
        config,
      });
  
      const image = extractImageFromResponse(response);
      const text = extractTextFromResponse(response);
  
      if (!image) {
        const fallbackMsg = text || "이미지가 생성되지 않았습니다.";
        return { success: false, text: fallbackMsg, outputPath: null };
      }
  
      ensureDir(outputPath);
      const finalPath = outputPath.match(/\.\w+$/)
        ? outputPath
        : outputPath + getExtFromMimeType(image.mimeType);
  
      fs.writeFileSync(finalPath, Buffer.from(image.data, "base64"));
  
      return { success: true, outputPath: finalPath, text: text || "" };
    } catch (error) {
      if (isOverloadError(error)) {
        return {
          success: false,
          text: `API 과부하 에러 (${model}). model: "${FALLBACK_MODEL}" 옵션으로 다시 시도해보세요.`,
          outputPath: null,
          overloaded: true,
        };
      }
      throw error;
    }
  }

• server.js:26-41 (schema)

  Zod schema defining input parameters for generate_image tool: prompt (string, required), outputPath (string, required), aspectRatio (enum with 10 options, optional), imageSize (enum: 1K/2K/4K, optional), model (string, optional).

  {
    prompt: z.string().describe("이미지 생성을 위한 텍스트 프롬프트"),
    outputPath: z.string().describe("생성된 이미지를 저장할 파일 경로"),
    aspectRatio: z
      .enum(["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"])
      .optional()
      .describe("이미지 비율 (기본: 1:1)"),
    imageSize: z
      .enum(["1K", "2K", "4K"])
      .optional()
      .describe("이미지 크기 (기본: 1K). 4K는 pro 모델만 지원"),
    model: z
      .string()
      .optional()
      .describe("사용할 모델 (기본: gemini-3-pro-image-preview)"),
  },

• server.js:23-78 (registration)

  MCP tool registration for generate_image. Defines tool name, description, input schema, and the handler function that calls generateImage and formats the response for the MCP protocol.

  server.tool(
    "generate_image",
    "텍스트 프롬프트로 이미지를 생성합니다",
    {
      prompt: z.string().describe("이미지 생성을 위한 텍스트 프롬프트"),
      outputPath: z.string().describe("생성된 이미지를 저장할 파일 경로"),
      aspectRatio: z
        .enum(["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"])
        .optional()
        .describe("이미지 비율 (기본: 1:1)"),
      imageSize: z
        .enum(["1K", "2K", "4K"])
        .optional()
        .describe("이미지 크기 (기본: 1K). 4K는 pro 모델만 지원"),
      model: z
        .string()
        .optional()
        .describe("사용할 모델 (기본: gemini-3-pro-image-preview)"),
    },
    async ({ prompt, outputPath, aspectRatio, imageSize, model }) => {
      try {
        const result = await generateImage(prompt, {
          outputPath,
          aspectRatio,
          imageSize,
          model,
        });
  
        if (!result.success) {
          return {
            content: [{ type: "text", text: result.text }],
            isError: !result.overloaded,
          };
        }
  
        return {
          content: [
            {
              type: "text",
              text: `이미지가 생성되었습니다: ${result.outputPath}${result.text ? "\n\n" + result.text : ""}`,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `이미지 생성 실패: ${error.message}`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• gemini-image.js:99-110 (helper)

  Helper function buildConfig that constructs the configuration object for the API call. Handles response modalities (TEXT, IMAGE), aspectRatio, and imageSize options.

  function buildConfig(options = {}) {
    const config = {
      responseModalities: ["TEXT", "IMAGE"],
    };
    if (options.aspectRatio) {
      config.aspectRatio = options.aspectRatio;
    }
    if (options.imageSize) {
      config.imageSize = options.imageSize;
    }
    return config;
  }

• gemini-image.js:44-58 (helper)

  Helper function extractImageFromResponse that extracts the base64-encoded image data and MIME type from the Gemini API response structure.

  function extractImageFromResponse(response) {
    const candidates = response.candidates || [];
    for (const candidate of candidates) {
      const parts = candidate.content?.parts || [];
      for (const part of parts) {
        if (part.inlineData && part.inlineData.data) {
          return {
            data: part.inlineData.data,
            mimeType: part.inlineData.mimeType || "image/png",
          };
        }
      }
    }
    return null;
  }