Gemini Image Generator MCP Server

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/mcp_server_gemini_image_generator/server.py:272-300 (handler)

  The primary handler function for the 'transform_image_from_encoded' MCP tool. Decorated with @mcp.tool(), it handles base64-encoded image input, prompt translation, image loading, and delegates to transformation processing using Gemini AI.

  @mcp.tool()
  async def transform_image_from_encoded(encoded_image: str, prompt: str) -> Tuple[bytes, 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/mcp_server_gemini_image_generator/server.py:210-242 (helper)

  Helper function specifically used by the tool handler to parse and validate the base64-encoded image input into a PIL Image object.

  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/mcp_server_gemini_image_generator/server.py:185-208 (helper)

  Key helper function called by the tool handler to perform the actual Gemini-powered image transformation, integrating prompts and source image.

  async def process_image_transform(
      source_image: PIL.Image.Image, 
      optimized_edit_prompt: str, 
      original_edit_prompt: str
  ) -> Tuple[bytes, 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
      )

• src/mcp_server_gemini_image_generator/prompts.py:4-24 (helper)

  Helper function that generates the detailed prompt template used for image transformation requests to the Gemini model.

  def get_image_transformation_prompt(prompt: str) -> str:
      """Create a detailed prompt for image transformation.
      
      Args:
          prompt: text prompt
          
      Returns:
          A comprehensive prompt for Gemini image transformation
      """
      return f"""You are an expert image editing AI. Please edit the provided image according to these instructions:
  
  EDIT REQUEST: {prompt}
  
  IMPORTANT REQUIREMENTS:
  1. Make substantial and noticeable changes as requested
  2. Maintain high image quality and coherence 
  3. Ensure the edited elements blend naturally with the rest of the image
  4. Do not add any text to the image
  5. Focus on the specific edits requested while preserving other elements
  
  The changes should be clear and obvious in the result."""