Gemini Image Generator MCP

Instructions

Args:
    encoded_image: Base64 encoded image data with header. Must be in format:
                "data:image/[format];base64,[data]"
                Where [format] can be: png, jpeg, jpg, gif, webp, etc.
    prompt: Text prompt describing the desired transformation or modifications
    
Returns:
    Path to the transformed image file saved on the server

Implementation Reference

• src/gemini_image_mcp/server.py:272-301 (handler)

  Main handler function for transform_image_from_encoded tool, including registration via @mcp.tool(), input schema in docstring, and core logic that loads the base64 image, translates prompt, and processes transformation.

  @mcp.tool()
  async def transform_image_from_encoded(encoded_image: str, prompt: str) -> str:
      """Transform an existing image based on the given text prompt using Google's Gemini model.
  
      Args:
          encoded_image: Base64 encoded image data with header. Must be in format:
                      "data:image/[format];base64,[data]"
                      Where [format] can be: png, jpeg, jpg, gif, webp, etc.
          prompt: Text prompt describing the desired transformation or modifications
          
      Returns:
          Path to the transformed image file saved on the server
      """
      try:
          logger.info(f"Processing transform_image_from_encoded request with prompt: {prompt}")
  
          # Load and validate the image
          source_image, _ = await load_image_from_base64(encoded_image)
          
          # Translate the prompt to English
          translated_prompt = await translate_prompt(prompt)
          
          # Process the transformation
          return await process_image_transform(source_image, translated_prompt, prompt)
          
      except Exception as e:
          error_msg = f"Error transforming image: {str(e)}"
          logger.error(error_msg)
          return error_msg

• src/gemini_image_mcp/server.py:210-242 (helper)

  Helper function to load and validate the base64-encoded image into a PIL Image object, specifically used by the transform_image_from_encoded handler.

  async def load_image_from_base64(encoded_image: str) -> Tuple[PIL.Image.Image, str]:
      """Load an image from a base64-encoded string.
      
      Args:
          encoded_image: Base64 encoded image data with header
          
      Returns:
          Tuple containing the PIL Image object and the image format
      """
      if not encoded_image.startswith('data:image/'):
          raise ValueError("Invalid image format. Expected data:image/[format];base64,[data]")
      
      try:
          # Extract the base64 data from the data URL
          image_format, image_data = encoded_image.split(';base64,')
          image_format = image_format.replace('data:', '')  # Get the MIME type e.g., "image/png"
          image_bytes = base64.b64decode(image_data)
          source_image = PIL.Image.open(BytesIO(image_bytes))
          logger.info(f"Successfully loaded image with format: {image_format}")
          return source_image, image_format
      except ValueError as e:
          logger.error(f"Error: Invalid image data format: {str(e)}")
          raise ValueError("Invalid image data format. Image must be in format 'data:image/[format];base64,[data]'")
      except base64.binascii.Error as e:
          logger.error(f"Error: Invalid base64 encoding: {str(e)}")
          raise ValueError("Invalid base64 encoding. Please provide a valid base64 encoded image.")
      except PIL.UnidentifiedImageError:
          logger.error("Error: Could not identify image format")
          raise ValueError("Could not identify image format. Supported formats include PNG, JPEG, GIF, WebP.")
      except Exception as e:
          logger.error(f"Error: Could not load image: {str(e)}")
          raise

• src/gemini_image_mcp/server.py:185-208 (helper)

  Helper function that creates the transformation prompt and calls Gemini to process the image transformation, used by the handler.

  async def process_image_transform(
      source_image: PIL.Image.Image, 
      optimized_edit_prompt: str, 
      original_edit_prompt: str
  ) -> str:
      """Process image transformation with Gemini.
      
      Args:
          source_image: PIL Image object to transform
          optimized_edit_prompt: Optimized text prompt for transformation
          original_edit_prompt: Original user prompt for naming
          
      Returns:
          Path to the transformed image file
      """
      # Create prompt for image transformation
      edit_instructions = get_image_transformation_prompt(optimized_edit_prompt)
      
      # Process with Gemini and return the result
      return await process_image_with_gemini(
          [edit_instructions, source_image],
          original_edit_prompt
      )